Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.skills.video/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Common status codes

StatusMeaning
200Success
202Accepted for processing
400Invalid request
401Authentication required or failed
402Insufficient credits
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 has the same shape: a machine-readable error code and a sanitized human-readable message. Upstream vendor names are redacted from the message before it reaches your client. 
{
  "error": "IMAGE_GENERATION_RATE_LIMITED",
  "message": "Rate limit exceeded. Please retry later."
}

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

{
  "error": "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.
  • 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 { error, message } = await response.json();
  switch (error) {
    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);
  }
}