> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "error": {
    "message": "Error description",
    "type": "error_type"
  }
}
```

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"
  }
}
```

<Note>
  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.
</Note>

### 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:

```json theme={null}
{
  "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}
    ]
  }
}
```

<Tip>
  * 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).
</Tip>

## Task-Related Error Codes

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

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