HTTP Status & Error Codes

skills.video uses standard HTTP status codes alongside a machine-readable code to describe request outcomes. Use the HTTP status to decide whether to retry, fix input, or treat a request as successful; use code to branch on the specific failure reason. The error field is still returned for older clients.

Common status codes

Status	Meaning
200	Success
202	Accepted for processing
400	Invalid request
401	Authentication required or failed
402	Insufficient credits
403	Access forbidden
404	Resource not found
422	Validation error / content rejected
429	Rate limited
500	Server error
502	Upstream generation failed
503	Upstream provider unavailable
504	Generation timed out

Error response format

Every error body includes a machine-readable code and a sanitized human-readable message. Most responses also include error as a legacy compatibility field. New integrations should branch on code; older clients may continue reading error.

{
  "error": "IMAGE_GENERATION_RATE_LIMITED",
  "code": "IMAGE_GENERATION_RATE_LIMITED",
  "message": "Rate limit exceeded. Please retry later."
}

{
  "error": "TTS_GENERATION_TIMEOUT",
  "code": "TTS_GENERATION_TIMEOUT",
  "message": "Generation timed out."
}

{
  "error": "INSUFFICIENT_CREDITS",
  "code": "VIDEO_GENERATION_INSUFFICIENT_CREDITS",
  "message": "Insufficient credits for this generation."
}

Generation error codes

Generation endpoints return error codes from one of three families, matching the endpoint’s output type. Every family shares the same set of sub-codes.

Sub-code	Typical HTTP	When it fires
`FAILED`	502	Generic upstream failure. Safe default to branch on.
`TIMEOUT`	504	Generation exceeded the upstream timeout. Retry is usually safe.
`RATE_LIMITED`	429	Upstream rate limit hit. Back off and retry.
`PROVIDER_UNAVAILABLE`	503	Upstream provider is down. Retry with backoff.
`UNSUPPORTED_MODEL`	400	The requested `provider/model` combination is not supported.
`INVALID_INPUT`	400	Request body failed validation or was otherwise malformed.
`INSUFFICIENT_CREDITS`	402	Workspace does not have enough credits to run the generation.
`CONTENT_REJECTED`	422	Upstream moderation rejected the prompt or inputs.

Image generation

Returned by POST /generation/{provider}/{model} (and the SSE variant) when the model is an image model.

IMAGE_GENERATION_FAILED
IMAGE_GENERATION_TIMEOUT
IMAGE_GENERATION_RATE_LIMITED
IMAGE_GENERATION_PROVIDER_UNAVAILABLE
IMAGE_GENERATION_UNSUPPORTED_MODEL
IMAGE_GENERATION_INVALID_INPUT
IMAGE_GENERATION_INSUFFICIENT_CREDITS
IMAGE_GENERATION_CONTENT_REJECTED

Video generation

Returned by POST /generation/{provider}/{model} (and the SSE variant) when the model is a video model.

VIDEO_GENERATION_FAILED
VIDEO_GENERATION_TIMEOUT
VIDEO_GENERATION_RATE_LIMITED
VIDEO_GENERATION_PROVIDER_UNAVAILABLE
VIDEO_GENERATION_UNSUPPORTED_MODEL
VIDEO_GENERATION_INVALID_INPUT
VIDEO_GENERATION_INSUFFICIENT_CREDITS
VIDEO_GENERATION_CONTENT_REJECTED

TTS generation

Returned by POST /ai/tts/generate and by POST /generation/{provider}/{model} (and the SSE variant) when the model is a TTS model. Workspace credit errors apply only to workspace-backed /generation endpoints.

TTS_GENERATION_FAILED
TTS_GENERATION_TIMEOUT
TTS_GENERATION_RATE_LIMITED
TTS_GENERATION_PROVIDER_UNAVAILABLE
TTS_GENERATION_UNSUPPORTED_MODEL
TTS_GENERATION_INVALID_INPUT
TTS_GENERATION_INSUFFICIENT_CREDITS
TTS_GENERATION_CONTENT_REJECTED

Branching on errors

const response = await fetch(url, { method: "POST", ... });
if (!response.ok) {
  const { code, message } = await response.json();
  switch (code) {
    case "IMAGE_GENERATION_RATE_LIMITED":
    case "VIDEO_GENERATION_RATE_LIMITED":
    case "TTS_GENERATION_RATE_LIMITED":
      // back off and retry
      break;
    case "IMAGE_GENERATION_INSUFFICIENT_CREDITS":
    case "VIDEO_GENERATION_INSUFFICIENT_CREDITS":
    case "TTS_GENERATION_INSUFFICIENT_CREDITS":
      // surface a "top up credits" UI
      break;
    case "IMAGE_GENERATION_CONTENT_REJECTED":
    case "VIDEO_GENERATION_CONTENT_REJECTED":
    case "TTS_GENERATION_CONTENT_REJECTED":
      // ask the user to rewrite the prompt
      break;
    default:
      // generic handling using `message`
      showError(message);
  }
}

Get started

Billing

APIs

HTTP Status & Error Codes

Common status codes

Error response format

Generation error codes

Image generation

Video generation

TTS generation

Branching on errors

​Common status codes

​Error response format

​Generation error codes

​Image generation

​Video generation

​TTS generation

​Branching on errors

Common status codes

Error response format

Generation error codes

Image generation

Video generation

TTS generation

Branching on errors