Errors and retries

Handle failures and retry without duplicate orders.

Errors

Branch on code; message is for display and param identifies an invalid field. Include the response’s request-id header when contacting support.

json

{
  "error": {
    "code": "invalid_request",
    "message": "Send exactly one of media_url or upload_id.",
    "param": "media_url"
  }
}

Status	Code	Action
`400`	`invalid_request`	Fix `param`.
`401`	`missing_api_key`, `invalid_api_key`	Supply a valid key.
`402`	`insufficient_funds`, `budget_exceeded`	Add credit or adjust the budget.
`403`	`api_access_disabled`, `read_only_key`, `uploads_disabled`	Check workspace and key permissions.
`404`	`not_found`	Check the ID and workspace.
`409`	`captions_not_ready`	Wait for completion.
`409`	`job_cancelled`, `upload_already_used`	Check the job or use a new upload.
`413`, `415`	—	Check body size and JSON content type.
`422`	`media_unreachable`, `unsupported_media`, `media_too_long`, `format_unavailable`	Change the media or output format.
`429`, `503`	`rate_limited`, `temporarily_unavailable`	Wait for `Retry-After` seconds.

Retry reads after network errors, timeouts, and 5xx responses with backoff. Before retrying an order, see Create job to avoid duplicate charges. Fix other 4xx requests before retrying.