Error Codes & Troubleshooting Guide

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

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

Authentication Errors (401)

Code	Message	Solution
`MISSING_AUTH_HEADER`	Missing Authorization header	Add `Authorization: Bearer sk-xxx` header
`INVALID_AUTH_FORMAT`	Invalid Authorization format	Use `Bearer` prefix before your key
`INVALID_KEY_FORMAT`	Invalid API key format	Keys must start with `sk-`
`INVALID_API_KEY`	Invalid or inactive API key	Check your key or generate a new one

Request Errors (400)

Code	Message	Solution
`INVALID_JSON`	Invalid JSON body	Check your JSON syntax
`MISSING_MODEL`	model is required	Include `model` in request body
`MISSING_PROMPT`	prompt is required	Include `prompt` in request body
`INVALID_MODEL`	Invalid model	Use a valid model name from `/api/v1/models`

Credit Errors (402)

Code	Message	Solution
`INSUFFICIENT_CREDITS`	Not enough credits	Purchase more credits or use a cheaper model

Example response:

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

Rate Limit Errors (429)

Code	Message	Solution
`RATE_LIMITED`	Rate limit exceeded	Wait 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)

Code	Message	Solution
`FORBIDDEN`	API access requires an active subscription or credit pack	Purchase a subscription or credit pack at vicsee.com/pricing
`FORBIDDEN`	Access denied	You can only access your own tasks

Task Errors (404)

Code	Message	Solution
`TASK_NOT_FOUND`	Task not found	Check the task ID
`NO_RESULT`	No result available	Task may have failed silently

Server Errors (500, 502)

Code	Message	Solution
`PROVIDER_ERROR`	AI provider not available	Try again later
`GENERATION_FAILED`	Generation failed	Retry the request
`INTERNAL_ERROR`	Internal server error	Contact 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;
}

Errors

On this page