Skip to main content
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

StatusMeaning
200Success
202Accepted for processing
400Invalid request
401Authentication required or failed
402Insufficient credits
403Access forbidden
404Resource not found
422Validation error / content rejected
429Rate limited
500Server error
502Upstream generation failed
503Upstream provider unavailable
504Generation 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-codeTypical HTTPWhen it fires
FAILED502Generic upstream failure. Safe default to branch on.
TIMEOUT504Generation exceeded the upstream timeout. Retry is usually safe.
RATE_LIMITED429Upstream rate limit hit. Back off and retry.
PROVIDER_UNAVAILABLE503Upstream provider is down. Retry with backoff.
UNSUPPORTED_MODEL400The requested provider/model combination is not supported.
INVALID_INPUT400Request body failed validation or was otherwise malformed.
INSUFFICIENT_CREDITS402Workspace does not have enough credits to run the generation.
CONTENT_REJECTED422Upstream 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);
  }
}