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"
  }
}

The error field in a task query response also includes code: for failed tasks, it identifies the failure category; tasks still processing may instead return a delay notice with code=task_delayed and type=task_status. Use only status to determine whether a task has ended. Do not stop polling just because error is non-null or progress=100. Failure information uses the following format:

{
  "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).

A task query returning HTTP 200 means only that the query succeeded, not that the task has completed. Supported asynchronous tasks may return the following status notice after more than 30 minutes of processing:

Status Notice Code	Task Status and Type	Recommended Action
`task_delayed`	`status=processing`, `error.type=task_status`	Keep polling; read `message` for the actual processing deadline for this task. If the deadline has passed but the task has not ended, wait for the system to process it; this does not confirm a refund.

When status=failed, error.type=task_error and the error code identifies the failure category in a form safe to show to clients. For Gateway video, image, audio, and document tasks, a confirmed refund of reserved credits is reported by appending text to error.message, without changing the original public code or type. Tasks with no reserved credits require no refund. usage.credits_reserved can remain positive after a refund and does not indicate that a refund is still pending. Successful tasks always return error=null. For response examples, see Query Task Status. Error codes for failed tasks:

Error Code	Description	Recommended Action
`content_policy_violation`	Input content violates content policies	Modify the prompt and retry
`timeout`	Task processing timed out	Retry later; contact an administrator if failures persist
`model_unavailable`	The model is temporarily unavailable	Retry later; contact an administrator if failures persist
`service_unavailable`	The service is temporarily unavailable	Retry later; contact an administrator if failures persist

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