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
| 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 |
INVALID_SPEED | Speech speed out of range | speed must be between 0.7 and 1.2 |
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"
}
}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.
| Code | Status | Message | Solution |
|---|---|---|---|
CONTENT_POLICY_VIOLATION | 422 | This request was blocked: VicSee does not allow sexual or nude content | Change 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_UNAVAILABLE | 503 | This request could not be checked right now | Transient. Retry after a short wait; nothing was charged |
INPUT_URL_UNREACHABLE | 400 | The file at URL could not be fetched (HTTP status), or could not be reached | An 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)
| 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 limitX-RateLimit-Remaining- Requests remainingX-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;
}Tasks
Poll generation task status and retrieve AI-generated videos and images. Real-time progress updates, error handling, and direct download URLs for all completed generations.
Rate Limits
Understand VicSee API rate limits by plan tier. Free, Pro, and Enterprise quotas for daily requests, concurrent generations, and fair usage policies to ensure platform stability.