Errors and retries

Every API error uses the same JSON structure. Save request_id in your logs and include it when you contact support.

{
  "error": {
    "code": "invalid_request",
    "message": "Unsupported model.",
    "param": "model",
    "request_id": "req_2YgM6pg5oM2WkKpQ"
  }
}

Status	Meaning	Retry?
`400`	The body is not valid JSON	No. Fix the body
`401`	The API key is missing, invalid, or revoked	No. Replace the key
`402`	The account does not have enough available credits	No. Add credits or wait for reservations
`403`	The model or quality requires a higher plan	No. Change the input or plan
`404`	The task does not exist or belongs to another account	No
`415`	The content type is not `application/json`	No. Fix the header
`422`	A parameter is invalid, a model is unavailable, or a prompt is blocked	No. Fix the request
`429`	The API key reached its rate limit, or the account reached its concurrent task limit	Yes, with backoff
`500`	An internal error occurred	Yes, after a delay
`502`	The video provider could not start the task	Yes, after a delay
`503`	Generation or moderation is temporarily unavailable	Yes, after a delay

Retry safely

For 429, 500, 502, and 503, use exponential backoff with jitter and set a maximum retry count. You can safely poll GET /v1/tasks/{task_id}.

Create retries can produce duplicate tasks

The API does not support idempotency keys yet. If your client loses the response after POST /v1/videos/generations succeeds, retrying the POST can create a second task and reserve more credits. Record each returned task_id. Do not retry the POST automatically when you do not know whether the original request succeeded.

Retry safely

On this page