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

# Error reference

> Look up API request errors and task failure reasons, fix specific input issues, and recover uncertain submissions

First distinguish a failed request from a failed generation task. A code can cover several causes: `invalid_request` may mean that an image has invalid dimensions, rather than that the model does not accept images.

## Where to read the error

| Scenario | How to identify it | Fields to read |
| - | - | - |
| OpenAI-format request error | Non-success HTTP status or an error object | `error.code`, `error.message`, optional `error.param` and `error.type` |
| Request error on some task submission or query endpoints | Check both HTTP status and the response body | Top-level `code`, `message`, `data` |
| Task execution failure | The query succeeds, but task `status` is `failed` | `error.code`, optional `error.reason`, `error.message` |
| Failed task Webhook event | `type` is `generation.failed`, `data.status` is `FAILURE` | `data.error.code`, `data.error.message` |
| Video request recovery | Check the recovery record's `state` | Optional `error_code`, `message`, `task_id` |

Illustrative request error, with example wording:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "type": "toapis_error",
    "param": "",
    "message": "Image dimensions or aspect ratio do not meet this model's requirements."
  }
}
```

Illustrative task execution failure:

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "reason": "image_dimensions_multiple",
    "message": "Image dimensions must be multiples of 16."
  }
}
```

The multiple in the second example illustrates one constraint, not a limit shared by all models. HTTP 200 means that the query succeeded; check the task status too. A numeric business `code` is also distinct from HTTP status. For responses with `success: false`, inspect the body.

Use `code` to identify the error, `reason` when present to classify a task failure, and `message` to understand its specific cause. `error.type` is an error type, not necessarily the code. Messages can be localized; do not use exact message matching for application logic. Some authentication errors have an empty `code`, and some protocols provide only `type` and `message`.

## Request error lookup

These identifiers can occur on public requests; not every endpoint returns all of them. Models may preserve different original spellings. Use the response formats above to locate the fields.

| Error identifier | Possible causes | What to do |
| - | - | - |
| `invalid_request`, `invalid_request_error`, `invalid_params`, `InvalidParameter`, `invalid_parameter_error`, `invalid_value` | Invalid field types, image dimensions, media retrieval, message structure, or parameter combinations | Use `param` and `message` to locate the issue. See the specific cases below and correct the input before resubmitting |
| `invalid_json`, `invalid_multipart_form`, `read_request_body_failed` | Unparseable JSON or form data, or a failure to read the request body | Check serialization, `Content-Type`, and upload completeness |
| `unknown_parameter`, `unsupported_value`, `provider_capability_not_supported`, `not_supported` | A model does not accept a field, value, tool, or endpoint capability | Check the exact model's API documentation; remove the unsupported field or choose a model that supports the capability |
| `missing_model`, `model_not_found`, `unsupported_model`, `DeploymentNotFound` | Missing model name, inaccessible model, unsupported endpoint, or temporary service unavailability | Check the [model catalog](https://docs.toapis.com/docs/en/api-reference/models.md) and API Key permissions. If the name is correct and the message indicates temporary unavailability, retry later or contact support |
| `invalid_private_assets`, `invalid_image`, `invalid_image_file` | Invalid media references, undecodable images, excessive count or dimensions, or unreadable URLs | Check the specified media item and limits; export or upload it again before submitting |
| `access_denied`, or HTTP 401/403 without a code | Invalid, expired, or disabled API Key; IP or model access restrictions | Check the key and access permissions. An authentication error from the service does not always mean your own key is invalid |
| `insufficient_user_quota`, `quota_not_enough`, `token_quota_not_enough`, `pre_consume_token_quota_failed` | Insufficient account balance, Token allowance or periodic limit; allowance checks can also fail temporarily | Top up or adjust limits only when the message identifies your account or Token. For service-side quota or check failures, retry later or contact support |
| `rate_limit_exceeded`, `RateLimitReached`, `rate_limit_unavailable` | Request limits, model service throttling, or unavailable limit checks | Reduce concurrency, honor `Retry-After` when present, then use backoff with jitter. See [asynchronous rate limits](https://docs.toapis.com/docs/en/api-reference/rate-limits/async-tasks.md) |
| `get_channel_failed`, `all_channels_circuit_broken`, `provider_unavailable` | No available service for the model, or high load | Retry later; contact support if it persists. Changing image content is not required |
| `do_request_failed`, `first_output_timeout`, `up_timeout` | Connection, first-output, or response-read timeout; the request may have been accepted | Query an existing task ID first. For video requests without an ID, follow the recovery guidance below |
| `bad_response_status_code`, `bad_response`, `bad_response_body`, `read_response_body_failed`, `upstream_error`, `unknown_error` | Service error, or an unreadable or unparseable response | Check HTTP status and the message, and establish whether a task already exists. Contact support with the request ID if it persists |
| `convert_request_failed`, `model_price_error`, `pricing_failed`, `pricing_unavailable`, `internal_error` | Request conversion, pricing, or service processing failed; input is not necessarily at fault | Correct explicit field constraints in the message; otherwise retry later or contact support |
| `task_not_found`, `task_not_exist`, `request_not_found` | Missing task or recovery record, another account's ID, or an expired recovery record | Check the ID, account, and query endpoint. A missing recovery record does not prove that the original request never ran |
| `invalid_client_request_id`, `request_cache_unavailable`, `submission_unconfirmed` | Invalid recovery ID, unavailable recovery service, or unconfirmed submission | Correct the ID format, or wait and query the original request. Do not repeatedly submit with new IDs |
| `invalid_callback_url`, `callback_url_origin_mismatch`, `webhook_not_configured`, `webhook_configuration_invalid`, `webhook_configuration_unavailable`, `webhook_configuration_error`, `webhook_api_token_required` | Invalid callback URL or Token Webhook configuration, or temporarily unreadable configuration | Check HTTPS, origin, API Token, and configuration against the [task Webhook guide](https://docs.toapis.com/docs/en/api-reference/webhooks/task-webhooks.md) |
| `sensitive_words_detected`, `prompt_blocked`, `content_policy_violation`, `content_filter`, `content_filtered` | Input or output failed content review | Check the prompt and all reference media, revise compliant content, then resubmit. Do not automatically repeat the unchanged request |
| `invalid_encrypted_content` | Encrypted content in conversation output items could not be verified or parsed | Check whether the client modified or truncated previous output items, and preserve such items unchanged. Contact support if it persists; do not edit the encrypted content |

## What invalid\_request can mean

The following cases summarize diagnostics from real requests and failed tasks. They can be wrapped in a general parameter code, a specific `reason`, or an original model error code. **Read the field and explanation before deciding what to change.**

| Specific case | How to identify and fix it |
| - | - |
| Output size or aspect-ratio syntax mismatch | Some models accept ratios such as `1:1` in `size`; others accept pixel dimensions. Sending `1024x1024` to a ratio-only model fails. Follow the selected model's definitions for `size`, `resolution`, and `aspect_ratio` |
| Invalid width, height, total pixels, or dimension multiple | The image may be too small, too large, too wide, or not a required multiple. Establish whether the error refers to reference media or output dimensions, then resize or crop to that model's limits |
| Reference image file or count exceeds limits | Byte size, longest edge, total pixels, and image count are separate limits. File compression may reduce bytes without reducing pixels. Compress, resize, or remove images according to the error |
| Wrong image field type | An endpoint expecting an array of URL strings cannot parse an array of objects. `image_urls` and `image_with_roles` have different structures; some endpoints also reject Base64 or combining both fields |
| The URL exists but the service cannot retrieve the file | 403/404, login requirements, expired URLs, timeouts, hotlink protection, or an HTML response can cause failures. Supply a public direct-download URL valid long enough for processing, or use the [upload API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) first |
| Unsupported media format or duration | A valid extension does not guarantee decodable content. GIF, video codec, frame rate, individual duration, or total reference duration may violate the model's requirements. Export the media according to its documentation |
| Seedance task type conflicts with parameters | A request classified as video editing may require `aspect_ratio=adaptive` and `duration=-1`; extension may also require `adaptive`. `InvalidParameter.TaskTypeConstraint` can also mean the prompt and media imply another task type. See [Seedance 2.5](https://docs.toapis.com/docs/en/api-reference/videos/seedance-2-5/generation.md) |
| Invalid text, conversation history, or tool sequence | The prompt may be too long, the model may reject `developer` roles, `tool_calls` may lack matching tool results, or thinking mode may require `reasoning_content`. Correct the history for that model's protocol |
| A field exists but the model rejects it | Fields or values such as `quality`, `reasoning_effort`, `temperature`, `thinking`, and `enable_thinking` are not universal. `max_tokens` and `max_completion_tokens` may be mutually exclusive. Tool schemas and `response_format` must meet model requirements |

Numbers in historical failures are not platform-wide limits. Determine image input support from the model's capabilities, not from `invalid_request` or `invalid_image` alone.

## Task failure reason lookup

Once a task ID is returned, use its query status. Ordinary generation task failures commonly use `error.code=generation_failed`; the optional `error.reason` provides a more specific category. The following are reason values, not codes guaranteed on request errors.

If `error.input_media_errors` is present, read each item's `type`, `index`, and `message`. For example, `type=image`, `index=0` identifies the first image in the original request, so you can fix that specific item. These details are not available for every model or query format.

| error.reason | Possible causes and next steps |
| - | - |
| `invalid_input`, `missing_parameter` | Invalid input or a missing field. Check the specific cases above and the message, then correct the request |
| `reference_image_too_large`, `image_dimensions_multiple` | Reference image byte size or a dimension-multiple constraint. Check file size and pixel dimensions separately |
| `reference_media_unreadable`, `unsupported_media_format` | Unreachable URL, invalid file, or unsupported format. Check access and the actual media content |
| `unsupported_parameter_value`, `parameter_out_of_range`, `parameter_replacement_required` | Value outside the allowed set or range, or a field needs replacing. Follow the message and model documentation |
| `video_edit_parameters_required`, `unsupported_request_capability` | Invalid editing parameter combination, or unsupported model capability. Adjust task type, parameters, or model |
| `content_policy_rejected` | Prompt, reference image/video/audio, or generated output failed safety or copyright review. Check all inputs; compliant input can still produce a rejected output |
| `service_busy`, `request_rate_limited` | Busy service or throttling. Wait and lower the request rate |
| `generation_timeout` | Generation or task processing timed out. Check the existing task before resubmitting; do not recreate tasks still processing |
| `generation_unavailable`, `model_unavailable`, `model_region_unavailable` | Temporarily unavailable model service or unsupported access region. Check model and permissions; contact support if it persists |
| `insufficient_user_balance`, `token_quota_exceeded` | Insufficient account balance or API Token allowance. Check both and their periodic limits |
| `result_storage_failed` | Result storage or delivery failed, rather than necessarily unsupported input. Contact support with the task ID |
| `submission_pending_reconciliation` | Submission or generation outcome still needs confirmation. Keep the existing ID and wait for query results to avoid duplicate generation |
| `refund_pending` | Refund processing is incomplete. Check available billing information on a fresh query; contact support if it persists |
| `request_cancelled` | The request or task was cancelled. Confirm whether cancellation was intended before resubmitting |
| `generation_failed`, `service_error` | No more specific public reason, or internal service processing failed. Keep task and request IDs and contact support |

Some models preserve original errors such as `InvalidParameter.TaskTypeConstraint`, `RateLimitReached`, `InputImageSensitiveContentDetected`, or `OutputVideoSensitiveContentDetected`. This is not an exhaustive list; these examples can indicate task constraints, throttling, input review, or output review respectively.

Seedance Global queries may return original JSON values in `error.code` and `error.message`, including numbers or `null`, or omit them. OpenAI video format and Webhooks do not guarantee a `reason`. Handle unknown codes, missing fields, and varying field types; an original numeric code is not an HTTP status.

## Retries and request recovery

* Parameter, format, and content review issues: change the input before resubmitting. Repeating an unchanged request usually will not fix it.
* Throttling or temporary unavailability: honor `Retry-After` when present; otherwise use exponential backoff with jitter and bounded retries.
* Existing task ID: keep querying that task or receive [task Webhooks](https://docs.toapis.com/docs/en/api-reference/webhooks/task-webhooks.md). `queued` and `in_progress` are not failures and do not justify duplicate tasks.
* Video submission timeout or `submission_unconfirmed`: if the original request used `client_request_id`, call `GET /v1/video/requests/{client_request_id}` under the same account. Query the returned `task_id`; keep waiting for `submitting` or `unknown`. Only a recovery record with `state=failed` and `error_code=submission_rejected` confirms rejection and allows a new request as instructed. This recovery applies only to supported video endpoints using that field, not every API.

A failed task does not necessarily mean its refund is complete. Check available `billing` fields using the [billing guide](https://docs.toapis.com/docs/en/api-reference/account/pricing.md). Missing fields do not mean free usage or a completed refund. Webhooks are event snapshots and may differ from later query billing fields.

## Contacting support

Include request time and timezone, model, endpoint, HTTP status, request ID, available task ID, code/reason, and a redacted explanation. For image issues, include dimensions, format, and file size. Do not send API Keys, signed URLs, full prompts, or private media; use a minimal public example when reproduction is needed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.