Errors

Complete guide to VicSee API error codes. HTTP status codes, error response format, common issues, and solutions for authentication, rate limits, and generation failures.

The VicSee API uses conventional HTTP status codes and returns detailed error information in JSON format.

Error Response Format

All errors follow this structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

HTTP Status Codes

StatusDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
402Payment Required - Insufficient credits
403Forbidden - Access denied
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limit exceeded
500Internal Error - Server-side issue
502Bad Gateway - Upstream provider error

Authentication Errors (401)

CodeMessageSolution
MISSING_AUTH_HEADERMissing Authorization headerAdd Authorization: Bearer sk-xxx header
INVALID_AUTH_FORMATInvalid Authorization formatUse Bearer prefix before your key
INVALID_KEY_FORMATInvalid API key formatKeys must start with sk-
INVALID_API_KEYInvalid or inactive API keyCheck your key or generate a new one

Request Errors (400)

CodeMessageSolution
INVALID_JSONInvalid JSON bodyCheck your JSON syntax
MISSING_MODELmodel is requiredInclude model in request body
MISSING_PROMPTprompt is requiredInclude prompt in request body
INVALID_MODELInvalid modelUse a valid model name from /api/v1/models
INVALID_SPEEDSpeech speed out of rangespeed must be between 0.7 and 1.2

Credit Errors (402)

CodeMessageSolution
INSUFFICIENT_CREDITSNot enough creditsPurchase more credits or use a cheaper model

Example response:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Required: 60, Available: 45"
  }
}

Content Policy Errors (422, 503)

Every generation request is checked before it runs: the prompt, any other text, and every input image. VicSee does not allow sexual or nude content, of anyone, real or fictional. A blocked request creates no task and uses no credits.

CodeStatusMessageSolution
CONTENT_POLICY_VIOLATION422This request was blocked: VicSee does not allow sexual or nude contentChange the prompt or the input image. Do not retry the same request: repeated blocks suspend the account, and any sexual content involving a minor suspends it immediately
MODERATION_UNAVAILABLE503This request could not be checked right nowTransient. Retry after a short wait; nothing was charged
INPUT_URL_UNREACHABLE400The file at URL could not be fetched (HTTP status), or could not be reachedAn input image or video URL returned 4xx, or its host could not be connected to (dead link, DNS not found). Fix the URL (public, still exists) and resend. Retrying the same URL will not help; nothing was charged

Example response:

{
  "success": false,
  "error": {
    "code": "CONTENT_POLICY_VIOLATION",
    "message": "This request was blocked: VicSee does not allow sexual or nude content. Repeated attempts suspend the account."
  }
}

Rate Limit Errors (429)

CodeMessageSolution
RATE_LIMITEDRate limit exceededWait until reset time, shown in response

Example response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Limit: 500/day. Resets at: 2024-12-28T00:00:00.000Z"
  }
}

Check rate limit headers in any response:

  • X-RateLimit-Limit - Your daily limit
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - When limit resets

Access Errors (403)

CodeMessageSolution
FORBIDDENAPI access requires an active subscription or credit packPurchase a subscription or credit pack at vicsee.com/pricing
FORBIDDENAccess deniedYou can only access your own tasks

Task Errors (404)

CodeMessageSolution
TASK_NOT_FOUNDTask not foundCheck the task ID
NO_RESULTNo result availableTask may have failed silently

Server Errors (500, 502)

CodeMessageSolution
PROVIDER_ERRORAI provider not availableTry again later
GENERATION_FAILEDGeneration failedRetry the request
INTERNAL_ERRORInternal server errorContact support if persistent

Error Handling Example

async function generate(model, prompt) {
  const response = await fetch('https://vicsee.com/api/v1/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ model, prompt })
  });

  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case 'INSUFFICIENT_CREDITS':
        throw new Error('Please purchase more credits');
      case 'RATE_LIMITED':
        throw new Error('Too many requests, please wait');
      case 'INVALID_MODEL':
        throw new Error(`Unknown model: ${model}`);
      default:
        throw new Error(data.error.message);
    }
  }

  return data.data;
}