Skip to main content

​
Error Codes

This page documents all possible API response codes and error types.

​
Response Format

​
Success Response

When a request is successful, the API returns a response with code: 200: 
{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "not_started",
    "created_time": "2025-11-12T10:30:00"
  }
}

​
Error Response

When an error occurs, the API returns a response with the corresponding error code: 
{
  "code": 400,
  "error": {
    "message": "task_id is required",
    "type": "validation_error"
  }
}

​
Task Failed Response

When a task fails during processing, the response includes status: "failed" with an error message: 
{
  "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

​
200 - Success

Request completed successfully. Check the status field in the response to determine task state.

​
400 - Bad Request

The request contains invalid parameters or data.
TypeDescription
validation_errorParameter validation error
content_moderation_errorContent moderation error
content_too_long_errorContent exceeds maximum length
file_format_errorInvalid file format
Example: 
{
  "code": 400,
  "error": {
    "message": "task_id is required",
    "type": "validation_error"
  }
}

​
402 - Payment Required

Insufficient account balance or credits.
TypeDescription
insufficient_credits_errorInsufficient credits
Example: 
{
  "code": 402,
  "error": {
    "message": "Insufficient credits to complete this request",
    "type": "insufficient_credits_error"
  }
}

​
403 - Forbidden

Access denied due to permission restrictions.
TypeDescription
permission_denied_errorPermission denied
Example: 
{
  "code": 403,
  "error": {
    "message": "You do not have permission to access this resource",
    "type": "permission_denied_error"
  }
}

​
404 - Not Found

The requested resource does not exist.
TypeDescription
resource_not_found_errorResource not found
Example: 
{
  "code": 404,
  "error": {
    "message": "Task not found",
    "type": "resource_not_found_error"
  }
}

​
408 - Request Timeout

The request took too long to process.
TypeDescription
timeout_errorRequest timeout
Example: 
{
  "code": 408,
  "error": {
    "message": "Request timed out",
    "type": "timeout_error"
  }
}

​
429 - Too Many Requests

Rate limit exceeded.
TypeDescription
rate_limit_errorRate limit exceeded
Example: 
{
  "code": 429,
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "type": "rate_limit_error"
  }
}

​
500 - Internal Server Error

An unexpected server error occurred.
TypeDescription
internal_errorInternal server error
Example: 
{
  "code": 500,
  "error": {
    "message": "An internal error occurred. Please try again later.",
    "type": "internal_error"
  }
}

​
502 - Bad Gateway

Upstream service error.
TypeDescription
upstream_errorUpstream service error
Example: 
{
  "code": 502,
  "error": {
    "message": "Upstream service unavailable",
    "type": "upstream_error"
  }
}

​
503 - Service Unavailable

The service is temporarily unavailable.
TypeDescription
service_errorService unavailable
Example: 
{
  "code": 503,
  "error": {
    "message": "The server is busy. Please try again later.",
    "type": "service_error"
  }
}

​
Error Handling Best Practices

Implement retry logic: For 500, 502, and 503 errors, implement exponential backoff retry logic.
Handle rate limits: When receiving 429 errors, wait before retrying. Consider implementing request queuing.
Validate inputs: Check your request parameters before sending to avoid 400 errors.
Monitor credits: Keep track of your credit balance to avoid 402 errors during critical operations.