> ## 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.

# HTTP Status & Error Codes

> Standard HTTP responses and generation error codes used by skills.video APIs

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`.

```json theme={null}
{
  "error": "IMAGE_GENERATION_RATE_LIMITED",
  "code": "IMAGE_GENERATION_RATE_LIMITED",
  "message": "Rate limit exceeded. Please retry later."
}
```

```json theme={null}
{
  "error": "TTS_GENERATION_TIMEOUT",
  "code": "TTS_GENERATION_TIMEOUT",
  "message": "Generation timed out."
}
```

```json theme={null}
{
  "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

```ts theme={null}
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);
  }
}
```