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

# Errors

> HTTP status codes and per-item error shapes for the Knowlify API

## Status codes

| Code  | Meaning                | Typical cause                                                                                                                                                                                                                                                |
| ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200` | Success                | Request accepted. Inspect `results[].status` for per-item outcomes — some may still be `"error"`.                                                                                                                                                            |
| `400` | Bad Request            | Pydantic validation failed (bad enum, oversized batch, malformed URL or hex color), or `org_id` in body mismatches the API key's org.                                                                                                                        |
| `401` | Unauthorized           | `X-API-Key` / `Authorization` header missing, malformed, or revoked.                                                                                                                                                                                         |
| `402` | Payment Required       | `/v1/edits` rejected the request because the account balance is below the worst-case credit cost of the edit. `detail` is `"INSUFFICIENT_CREDITS: edit could cost up to <N>, have <M>"`. See [Credit cost](/api-reference/create-edit#credit-cost).          |
| `403` | Forbidden              | JWT caller is not an active member of the requested organization, or an API key is being used against a resource it does not own.                                                                                                                            |
| `404` | Not Found              | The target `video_uuid` or `edit_id` does not exist.                                                                                                                                                                                                         |
| `409` | Conflict               | `/v1/edits` — target video is still being built or has errored; or `/v1/edits/{edit_id}/revert` was rejected by one of the revert guards (active edit on the video, a newer external edit exists, or the top of `planner_history` does not match this edit). |
| `415` | Unsupported Media Type | A `reference_image_urls[]` entry returned the wrong `Content-Type` (must be `image/*`), exceeded 5 MB, or was missing `Content-Length` on the upstream `HEAD` response.                                                                                      |
| `422` | Unprocessable Entity   | Body is not valid JSON, or a reference image URL failed the SSRF host check (non-https, private/loopback/link-local IP, or more than one redirect hop).                                                                                                      |
| `429` | Too Many Requests      | Per-caller rate limit exceeded. See [Rate Limits](/api-reference/rate-limits).                                                                                                                                                                               |
| `500` | Internal Server Error  | Unexpected server failure. Per-item failures normally surface as `200` with `status: "error"` rows; a `500` indicates the request itself could not be handled.                                                                                               |

All non-2xx responses share the same envelope:

```json theme={null}
{ "detail": "<human-readable description>" }
```

## Per-item errors

`POST /v1/videos` returns `200` even when some items fail validation or queueing — your client should iterate `results` and retry only the failed entries.

A failed result entry looks like:

```json theme={null}
{
  "index": 3,
  "uuid": "550e8400-e29b-41d4-a716-446655440099",
  "session_id": "...",
  "chat_url": "...",
  "status": "error",
  "code": "ITEM_FAILED",
  "message": "voice_id was rejected by the upstream provider"
}
```

| Field     | Meaning                                                                                 |
| --------- | --------------------------------------------------------------------------------------- |
| `status`  | Always `"error"` for failed items.                                                      |
| `code`    | Machine-readable error code. Currently `"ITEM_FAILED"` is the only value emitted.       |
| `message` | Human-readable description suitable for logs.                                           |
| `index`   | Position of the failed item in the original request — use to correlate with your input. |

## Retry guidance

| Status                        | Retry?            | How                                               |
| ----------------------------- | ----------------- | ------------------------------------------------- |
| `429`                         | Yes               | Wait `Retry-After` seconds, then retry.           |
| `500`                         | Yes, with backoff | Exponential backoff starting at 2 s.              |
| `400` / `401` / `403` / `422` | No                | Fix the request first.                            |
| `402`                         | After top-up      | Add credits to the account, then resubmit.        |
| `200` with per-item `"error"` | Yes, per item     | Resubmit only the failing items in a new request. |

<Tip>
  If you see repeated `500`s on a previously working integration, email [info@knowlify.com](mailto:info@knowlify.com) with a request ID.
</Tip>