Getting started
Errors
HTTP status codes, error envelopes and task failure states.
Error envelope
Every failed request returns a non-2xx status and a JSON body in the same shape:
{
"ok": false,
"error": "NOT_ENOUGH_CREDITS",
"message": "Not enough credits: this generation costs 12."
}error is a stable machine-readable code; message is human-readable and may change. Branch on error, not on the wording.
Status codes
| Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | Malformed JSON body or missing field. |
| 400 | INVALID_IMAGE_REQUEST | An image parameter is invalid: unknown model, bad ratio, oversized reference image, too many references. |
| 400 | INVALID_VIDEO_REQUEST | A video parameter is invalid: unknown model or variant, unsupported duration, size or ratio. |
| 401 | UNAUTHORIZED | Missing, invalid, revoked or expired API key. |
| 402 | NOT_ENOUGH_CREDITS | The account cannot cover the generation cost. |
| 403 | UNAUTHORIZED | The account is disabled. |
| 404 | GENERATION_NOT_FOUND | No such task, or it belongs to another account. |
| 429 | CONCURRENCY_LIMIT | Too many tasks are already running for the account's plan. |
| 500 | INTERNAL_ERROR | Unexpected server error. |
| 503 | SERVICE_CONFIGURATION | The requested capability is not configured on the server. |
| 503 | MODEL_UNAVAILABLE | The requested video model is temporarily unavailable. |
Task failure is not an HTTP error
A task that is accepted and later fails still returns 200 from the polling endpoint. Check the task fields:
{
"ok": true,
"generation": {
"id": "gen_2f1c9a...",
"status": "failed",
"error": "The model rejected this prompt (content policy).",
"durationMs": 3200,
"imageUrls": []
}
}status | Meaning |
|---|---|
generating | Still running; keep polling. |
success | Finished; read imageUrls or videoUrls. |
failed | Finished with an error; read error. |
Credits for a failed task are returned automatically. A failed task is not retried: submit a new request if you want to try again.
Retrying safely
- Retry
429and5xxresponses with exponential backoff. - Do not retry
400,401/403,402or404without changing the request; they will fail again. - Every accepted
POSTcreates a new task and charges credits, so a blind retry after a timeout can double-charge. Read the error first — if the request was rejected before acceptance, retrying is safe.