Error reference

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:

{
  "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:

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

Overview

Quick Start

Model Catalog

Chat API

Image API

Video API

Music API

Task Management

File Uploads

Account

FAQs

Where to read the error

Request error lookup

What invalid_request can mean

Task failure reason lookup

Retries and request recovery

Contacting support

​Where to read the error

​Request error lookup

​What invalid_request can mean

​Task failure reason lookup

​Retries and request recovery

​Contacting support

Where to read the error

Request error lookup

What invalid_request can mean

Task failure reason lookup

Retries and request recovery

Contacting support