Errors - Knowlify

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

{ "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:

{
  "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.

If you see repeated 500s on a previously working integration, email [email protected] with a request ID.

⌘I