> ## Documentation Index
> Fetch the complete documentation index at: https://docs.captioncraft.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Distinguish request failures from processing failures.

## Request errors

An unsuccessful API request returns an appropriate HTTP status and a JSON error object:

```json theme={"system"}
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "No prepaid seconds available. Add credits before submitting a video.",
    "request_id": "<REQUEST_ID>"
  }
}
```

Record `error.request_id` or the `X-Request-Id` response header when reporting a problem. Do not include your API key in logs or support messages.

| HTTP | Code                   | Action                                                                          |
| ---- | ---------------------- | ------------------------------------------------------------------------------- |
| 400  | `INVALID_REQUEST`      | Correct invalid or unknown JSON fields.                                         |
| 400  | `INVALID_JSON`         | Send valid JSON.                                                                |
| 401  | `UNAUTHORIZED`         | Check the Bearer key and whether it expired or was revoked.                     |
| 402  | `INSUFFICIENT_CREDITS` | Add prepaid credit before submitting a video.                                   |
| 403  | `FORBIDDEN`            | Check key scopes and account access.                                            |
| 404  | `NOT_FOUND`            | Check the endpoint, job ID, and account that owns the job.                      |
| 413  | `PAYLOAD_TOO_LARGE`    | Keep the request's JSON body within 16 KiB.                                     |
| 415  | `INVALID_CONTENT_TYPE` | Set `Content-Type: application/json`.                                           |
| 429  | `RATE_LIMITED`         | Wait for `Retry-After` before retrying.                                         |
| 429  | `CONCURRENCY_LIMIT`    | Wait for capacity on the account.                                               |
| 500  | `INTERNAL_ERROR`       | Retry polling with backoff. For submissions, check recent jobs before retrying. |
| 503  | `SERVICE_UNAVAILABLE`  | Processing is not configured; contact the operator.                             |

## Processing errors

A job may be accepted and later fail. [Get job](/api-reference/get-job) still returns HTTP `200`; inspect `status` and `error`:

```json theme={"system"}
{
  "status": "failed",
  "error": {
    "code": "UNSUPPORTED_VIDEO",
    "message": "Unsupported video, missing audio, or exceeded duration/resolution limits."
  },
  "usage": { "reserved_seconds": 0, "billed_seconds": 0 }
}
```

This is an excerpt of a job response. Common processing codes include:

| Code                   | Meaning                                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `INVALID_SOURCE`       | The source could not be downloaded safely. Check URL expiry, redirects, permissions, and file size.        |
| `UNSUPPORTED_VIDEO`    | The video is unsupported, lacks audio, or exceeds the duration or resolution limit.                        |
| `INSUFFICIENT_CREDITS` | The available balance could not cover the inspected duration rounded up. Add credits and submit a new job. |
| `NO_SPEECH`            | No speech was detected.                                                                                    |
| `TRANSCRIPTION_FAILED` | Transcription did not complete.                                                                            |
| `RENDER_FAILED`        | Rendering or output preparation did not complete.                                                          |
| `QUEUE_TIMEOUT`        | Processing capacity was not available before the queue deadline.                                           |
| `WORKER_TIMEOUT`       | Processing timed out.                                                                                      |
| `ACCOUNT_DISABLED`     | Account access was disabled before processing.                                                             |

Failed jobs release reserved credits. Fix the underlying issue, then submit a new request if you want another attempt.