Error Handling

Error Response Format

All error responses use this structure:

1
{
2
  "type": "error",
3
  "error": {
4
    "type": "error_type",
5
    "message": "Human-readable error message"
6
  }
7
}

HTTP Status Codes

400 - Bad Request

Error Type: invalid_request_error

Invalid request parameters or validation errors.

1
{
2
  "type": "error",
3
  "error": {
4
    "type": "invalid_request_error",
5
    "message": "prompt is required"
6
  }
7
}

401 - Unauthorized

Error Type: authentication_error

Missing or invalid API key.

1
{
2
  "type": "error",
3
  "error": {
4
    "type": "authentication_error",
5
    "message": "Missing authorization header"
6
  }
7
}

402 - Payment Required

Error Type: insufficient_funds_error

Your account does not have enough credits to complete this request. This occurs when the estimated cost of the video generation exceeds your available balance.

1
{
2
  "type": "error",
3
  "error": {
4
    "type": "insufficient_funds_error",
5
    "message": "Insufficient funds. Required: 120 credits"
6
  }
7
}

Resolution:

• Check your current balance in your account dashboard
• Add credits to your account before retrying the request
• Consider generating a shorter video or using a lower resolution to reduce cost

See Pricing for details on video generation costs.

413 - Payload Too Large

Error Type: request_too_large

Request exceeds the maximum allowed number of bytes. This error is returned from the infrastructure layer before the request reaches the API. See Input Formats for size limits.

422 - Content Filtered

Error Type: content_filtered_error

Content rejected by safety filters.

1
{
2
  "type": "error",
3
  "error": {
4
    "type": "content_filtered_error",
5
    "message": "Content is filtered due to policy restrictions"
6
  }
7
}

429 - Too Many Requests

Error Types: rate_limit_error, concurrency_limit_error

Rate limit or concurrency limit exceeded. See Rate Limits for details.

500 - Internal Server Error

Error Type: api_error

Unexpected server error.

1
{
2
  "type": "error",
3
  "error": {
4
    "type": "api_error",
5
    "message": "Internal server error"
6
  }
7
}

503 - Service Unavailable

Error Type: service_unavailable

Service temporarily unavailable.

1
{
2
  "type": "error",
3
  "error": {
4
    "type": "service_unavailable",
5
    "message": "Service temporarily unavailable"
6
  }
7
}