Skip to main content

​
Status codes

CodeMeaningTypical cause
200SuccessRequest accepted. Inspect results[].status for per-item outcomes — some may still be "error".
400Bad RequestPydantic validation failed (bad enum, oversized batch, malformed URL or hex color), or org_id in body mismatches the API key’s org.
401UnauthorizedX-API-Key / Authorization header missing, malformed, or revoked.
403ForbiddenJWT caller is not an active member of the requested organization.
422Unprocessable EntityBody is not valid JSON.
429Too Many RequestsPer-caller rate limit exceeded. See Rate Limits.
500Internal Server ErrorUnexpected 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"
}
FieldMeaning
statusAlways "error" for failed items.
codeMachine-readable error code. Currently "ITEM_FAILED" is the only value emitted.
messageHuman-readable description suitable for logs.
indexPosition of the failed item in the original request — use to correlate with your input.

​
Retry guidance

StatusRetry?How
429YesWait Retry-After seconds, then retry.
500Yes, with backoffExponential backoff starting at 2 s.
400 / 401 / 403 / 422NoFix the request first.
200 with per-item "error"Yes, per itemResubmit 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.