Documentation Index
Fetch the complete documentation index at: https://docs.foxapi.cc/llms.txt
Use this file to discover all available pages before exploring further.
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": {
"message": "Error description",
"type": "error_type"
}
}
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) |
{
"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) |
{
"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).
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
