Match Every Response Code to the Right Handling Logic
Read the response shapes#
Success:
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}Error:
{
"code": 400,
"error": {
"message": "task_id is required",
"type": "validation_error"
}
}Task failed (the request itself succeeded; the generation did not):
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "failed",
"files": [],
"created_time": "2025-11-25T08:50:13",
"error_message": "The prompt violates our content policy"
}
}Business status codes#
| Code | Type(s) | Meaning |
|---|---|---|
| 200 | — | Request completed successfully; check status for task state |
| 400 | validation_error, content_moderation_error, content_too_long_error, file_format_error |
Invalid parameters or data |
| 402 | insufficient_credits_error |
Insufficient account balance or credits |
| 403 | permission_denied_error |
Access denied due to permission restrictions |
| 404 | resource_not_found_error |
The requested resource does not exist |
| 408 | timeout_error |
The request took too long to process |
| 429 | rate_limit_error |
Rate limit exceeded |
| 500 | internal_error |
An unexpected server error occurred |
| 502 | upstream_error |
Upstream service error |
| 503 | service_error |
The service is temporarily unavailable |
Example — 402 Payment Required:
{
"code": 402,
"error": {
"message": "Insufficient credits to complete this request",
"type": "insufficient_credits_error"
}
}Example — 429 Too Many Requests:
{
"code": 429,
"error": {
"message": "Rate limit exceeded. Please try again later.",
"type": "rate_limit_error"
}
}Handle errors correctly#
- Retry with backoff — for 500, 502, and 503 errors, implement exponential backoff retry logic.
- Respect rate limits — when receiving 429 errors, wait before retrying and consider request queuing.
- Validate before sending — check request parameters before sending to avoid 400 errors.
- Track credit balance — monitor credits to avoid 402 errors during critical operations.