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.
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 [e-mail] with a request ID.