Error Codes Reference

HTTP Status Codes

Status Code	Description	Common Causes
`200`	Success	Request processed successfully
`400`	Bad Request	Invalid JSON format, incorrect Content-Type
`401`	Unauthorized	API Key is invalid, expired, or missing
`402`	Payment Required	Insufficient account balance, please top up and retry
`404`	Not Found	Task ID does not exist
`422`	Unprocessable Entity	Missing required fields, invalid parameter values, model does not exist
`429`	Too Many Requests	Rate limit exceeded, please retry later
`500`	Internal Server Error	Server-side unknown error, please retry later
`503`	Service Unavailable	No available channels for the current model or upstream service error, please retry later

Error Response Format

All error responses follow this format:

{
  "error": {
    "message": "Error description",
    "type": "error_type"
  }
}

When a task fails, the error field in the task query response includes an additional code field:

{
  "error": {
    "code": "specific_error_code",
    "message": "Error description",
    "type": "task_error"
  }
}

Error Types

Error Type	Status Code	Description
`invalid_request_error`	400, 422	Invalid request format or parameter validation failed
`authentication_error`	401	API Key is invalid, expired, or missing
`insufficient_quota`	402	Insufficient account balance
`not_found`	404	The requested resource does not exist
`rate_limit_error`	429	Rate limit exceeded
`server_error`	500	Internal server error
`service_unavailable_error`	422	Model temporarily unavailable (no available channels)

Submission Stage Error Codes

When submitting a task, if parameter validation passes but channel matching fails, a 422 status code is returned with the following error codes in the error.code field:

Error Code	Description	Recommended Action
`unsupported_advanced_options`	No available channels currently support the advanced parameters in the request	Refer to the `unsupported_advanced_options` field in the response (each item contains the parameter name and default value); remove these parameters and retry
`param_constraints_unsatisfiable`	Parameter values exceed the range supported by currently available channels	Check whether parameter values are within the valid options documented in the API reference
`no_compatible_channel`	No available channels for this model at the moment	Retry later
`invalid_file_type`	The actual content of the media file does not match the expected type	Check whether the file is corrupted or the extension does not match the content

File Type Mismatch (invalid_file_type)

When submitting a task, the system performs content detection on media file URLs in the request (image_url, audio_url, video_url, etc.). If the actual format of the file does not match the expected type for the field (e.g., audio_url points to a file that is actually an archive), a 422 status code and invalid_file_type error code are returned. The response includes the following additional fields to help locate the issue:

Field	Description
`field`	The parameter name that triggered the validation failure (e.g., `audio_url`)
`detected_type`	The actual MIME type detected (e.g., `application/x-tar`)
`expected_type`	The expected media category (`image` / `audio` / `video`)

Example response:

{
  "error": {
    "message": "The file '002543212992.mp3' is detected as tar archive file (application/x-tar), not a valid audio file. Please verify the file content matches the expected format.",
    "type": "invalid_request_error",
    "code": "invalid_file_type",
    "field": "audio_url",
    "detected_type": "application/x-tar",
    "expected_type": "audio"
  }
}

File type detection is based on magic bytes in the file header, not the file extension or HTTP Content-Type header. If the file format is correct but cannot be recognized (e.g., uncommon encoding formats), the system will silently pass it through without blocking the request.

Advanced Options Not Supported (unsupported_advanced_options)

Some parameters are advanced options that are not supported by all channels. When the advanced parameters in the request are not supported by any available channel for the current model, a 422 status code and unsupported_advanced_options error code are returned. The response includes the following structured fields for programmatic parsing:

Field	Description
`model`	The model ID that triggered the error
`unsupported_advanced_options`	List of unsupported advanced parameters, each containing `param` (parameter name) and `default_value` (the default value for the parameter in the request schema; the system uses this value when the parameter is omitted)

Example response:

{
  "error": {
    "message": "The advanced options [enhance_prompt, seed] are not supported by any available channel for model 'veo-3.1'. Remove the unsupported options to proceed.",
    "type": "invalid_request_error",
    "code": "unsupported_advanced_options",
    "model": "veo-3.1",
    "unsupported_advanced_options": [
      {"param": "enhance_prompt", "default_value": false},
      {"param": "seed", "default_value": null}
    ]
  }
}

Advanced parameters are marked with x-advanced in each model’s API documentation. Removing unsupported advanced parameters does not affect core functionality, and generation results will still be normal.
default_value comes from the field’s default value in the request schema (null means the parameter is optional and the system will not apply any value when it is omitted).

When querying task status, tasks with a failed status will include the following error codes in the error.code field:

Error Code	Description	Recommended Action
`task_failed`	Task execution failed (general)	Resubmit the request
`content_policy_violation`	Input content violates content policies	Modify the prompt and retry
`invalid_image_url`	The provided image/video URL is inaccessible	Check whether the URL is publicly accessible
`file_too_large`	The uploaded file exceeds size limits	Reduce the file size
`unsupported_format`	Unsupported file format	Use a supported format

Rate Limits

Rate limits are applied per API Key
When rate limited, a 429 status code is returned; please wait and retry
Contact support if you need higher rate limits

Best Practices

Always check the HTTP status code before parsing the response body
Implement exponential backoff for retries on 429 and 5xx errors
Log error responses for debugging and troubleshooting
Poll task status at reasonable intervals recommended 3-5 seconds, avoid polling too frequently
Handle async tasks gracefully generation time varies by model; refer to the estimated time in each model’s documentation

Image Series

Video Series

Audio Series

Text Series

Document Processing

Task Management

File Management

Error Codes Reference

HTTP Status Codes

Error Response Format

Error Types

Submission Stage Error Codes

File Type Mismatch (invalid_file_type)

Advanced Options Not Supported (unsupported_advanced_options)

Rate Limits

Best Practices

​HTTP Status Codes

​Error Response Format

​Error Types

​Submission Stage Error Codes

​File Type Mismatch (invalid_file_type)

​Advanced Options Not Supported (unsupported_advanced_options)

​Task-Related Error Codes

​Rate Limits

​Best Practices

HTTP Status Codes

Error Response Format

Error Types

Submission Stage Error Codes

File Type Mismatch (invalid_file_type)

Advanced Options Not Supported (unsupported_advanced_options)

Task-Related Error Codes

Rate Limits

Best Practices