Errors
The error format, every error code, and which errors to retry.
Error format
Every error response has this shape:
{
"error": {
"code": "insufficient_balance",
"message": "Your available balance is not enough to create this task.",
"param": null,
"details": { "required": "1.50", "available": "0.80" },
"request_id": "rq_01jb..."
}
}| Field | Description |
|---|---|
code | Machine-readable error code. Branch on this. |
message | Human-readable explanation in English. The wording may change; don't match on it. |
param | The parameter that caused the error, or null. |
details | Optional extra information. |
request_id | Same as the X-Request-Id response header. |
Status codes and error codes
| Status | code | Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_request | A parameter is missing, has the wrong type or has an invalid value. | No. Fix the request. |
| 400 | invalid_media | The source video can't be read: the link doesn't open or has expired, isn't a public address, isn't a video or is in an unsupported format (mp4, mov, webm and mkv are supported). details.reason says why. | No. Use a different video URL. |
| 400 | video_too_long | The source video is longer than 30 seconds. details.video_duration is its length in seconds. | No. Trim it and create the task again. |
| 400 | video_too_short | The replace_object source video is shorter than 4 seconds. | No. |
| 401 | invalid_api_key | The API key doesn't exist, was deleted or has been reset. | No. |
| 402 | insufficient_balance | Your available balance can't cover the amount to freeze. details has the required amount and your available balance. | After you recharge. |
| 403 | account_suspended | Your account has been suspended. | No. |
| 404 | not_found | The task doesn't exist or doesn't belong to you. | No. |
| 429 | rate_limited | You exceeded a rate limit. | Yes, after Retry-After seconds. |
| 429 | too_many_inflight_tasks | You've reached the in-progress task limit (details.limit). | Yes, after one of your queued or running tasks finishes. |
| 500 | internal_error | Something went wrong on our side. No task was created. | Yes. |
| 503 | service_unavailable | The price can't be calculated right now. No task was created. | Yes, after Retry-After seconds. |
Handling errors
- Branch on
code, not on the status or the message: the two429s need different handling. 402 insufficient_balance:details.requiredis what this task needs anddetails.availableis your available balance. Recharge, then retry. See Billing.- An error response means nothing was created or charged.
Errors after a task is created
The codes above are returned by the request itself. A task that was accepted can still fail later, for example when a reference image can't be opened or the media violates the usage policy: it ends with status: "failed" and a reason in its error field (failure codes), and the frozen amount is returned in full.