Errors and Retries
Handle HTTP failures, business errors, and failed asynchronous tasks.
Standard API errors
Image, video, and utility endpoints normally return code, message, data, and timestamp. Successful responses use code: 1000; error responses normally have data: null. Check both the HTTP status and business code. Do not assume every error includes a request ID or a retryable field.
{
"code": 400,
"message": "model is required and must be a non-empty string.",
"data": null
}OpenAI-compatible chat endpoints may return { "error": { "message": "...", "type": "..." } }; Anthropic endpoints use their corresponding error format. Read the format documented for the endpoint instead of assuming a top-level message.
Status and recovery
| HTTP status | Action |
|---|---|
400 | Fix parameters, model ID, or input media before resubmitting. |
401 / 403 | Check the API key, its application, and required permissions. |
402 | Check the API balance; the business code may be 4001 or 1402. |
404 | Check the resource ID, task ownership, and model availability. |
409 | Retain the original idempotency key and check whether the request is still processing. |
429 | Reduce request frequency and use exponential backoff with jitter. |
Transient 5xx | Check the original request outcome before deciding whether to retry with backoff. |
Task failures and timeouts
An accepted generation can still fail. General task queries return status: "failed" and errorMessage; video cleanup uses the error object documented for that endpoint. Stop polling on either ready or failed.
A client timeout does not cancel server processing. Continue polling an existing taskId; if no ID was received, check usage records first. Cleanup and TTS can reuse the original Idempotency-Key. Do not assume the same idempotency protocol for general generations or video-to-prompt submissions.
See asynchronous tasks and Tools API.