> ## 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": "Insufficient available seconds for max_duration_seconds. Lower the limit or add credits.",
    "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.                                                       |
| 400  | `INVALID_IDEMPOTENCY_KEY` | Use 8–128 permitted characters.                                        |
| 401  | `UNAUTHORIZED`            | Check the Bearer key and whether it expired or was revoked.            |
| 402  | `INSUFFICIENT_CREDITS`    | Add credit or choose a duration limit that fits the video and balance. |
| 403  | `FORBIDDEN`               | Check key scopes and account access.                                   |
| 404  | `NOT_FOUND`               | Check the endpoint, job ID, and account that owns the job.             |
| 409  | `IDEMPOTENCY_CONFLICT`    | Use the original input, or a new key for a deliberately new 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 with backoff; preserve submission idempotency.                   |
| 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.                 |
| `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 with a **new** idempotency key if you want another attempt. A replay with the old key returns the existing failed job.