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

# 错误码速查

> 查询 API 请求错误和任务失败原因, 根据具体情况修正输入或恢复请求

先区分请求失败和任务执行失败, 再查错误标识与具体说明. 同一个错误码可能对应多种情况, 例如 `invalid_request` 可能是图片尺寸不符合要求, 不能据此判断模型不支持图片输入.

## 从哪里读取错误

| 场景 | 判断方式 | 要读取的字段 |
| - | - | - |
| OpenAI 格式的请求错误 | HTTP 非成功状态或响应包含错误对象 | `error.code`, `error.message`, 可选的 `error.param` 和 `error.type` |
| 部分任务提交或查询接口的请求错误 | HTTP 状态与响应体结合判断 | 顶层 `code`, `message`, `data` |
| 任务执行失败 | 查询成功, 但任务 `status` 为 `failed` | `error.code`, 可选的 `error.reason`, `error.message` |
| 任务 Webhook 失败事件 | `type` 为 `generation.failed`, `data.status` 为 `FAILURE` | `data.error.code`, `data.error.message` |
| 视频请求恢复 | 检查恢复记录的 `state` | 可选的 `error_code`, `message`, `task_id` |

请求错误示例, 文案仅用于说明:

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

任务执行失败示例:

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

第二个示例中的倍数只用于展示一种具体约束, 不适用于所有模型. 查询返回 HTTP 200 表示查询成功, 仍需检查任务状态. 数字业务 `code` 也不等于 HTTP 状态码; 返回 `success: false` 的接口需要检查响应体.

`code` 用于识别错误, `reason` 在提供时补充任务失败类别, `message` 用于阅读具体情况. `error.type` 是错误类型, 不一定等于错误码. 文案可能随语言变化, 不要通过完整匹配 `message` 控制业务逻辑. 部分鉴权响应的 `code` 为空, 部分协议只有 `type` 和 `message`.

## 请求错误速查

下表列出公开请求可能遇到的标识, 并非每个接口都会返回全部标识. 不同模型也可能保留不同的原始拼写. 字段位置按上表中的响应格式读取.

| 错误标识 | 可能的情况 | 建议操作 |
| - | - | - |
| `invalid_request`, `invalid_request_error`, `invalid_params`, `InvalidParameter`, `invalid_parameter_error`, `invalid_value` | 参数类型, 图片尺寸, 素材读取, 消息结构或参数组合不合法 | 根据 `param` 和 `message` 定位字段, 参考下方具体情况; 修改输入后再提交 |
| `invalid_json`, `invalid_multipart_form`, `read_request_body_failed` | JSON 或表单无法解析, 请求体读取失败 | 检查序列化结果, `Content-Type` 和上传是否完整 |
| `unknown_parameter`, `unsupported_value`, `provider_capability_not_supported`, `not_supported` | 模型不接受某个字段, 参数值, 工具或接口能力 | 检查精确模型的接口说明; 移除不支持的字段或使用支持该能力的模型 |
| `missing_model`, `model_not_found`, `unsupported_model`, `DeploymentNotFound` | 缺少模型名, 模型不可访问, 当前入口不支持, 或服务暂不可用 | 核对[模型目录](https://docs.toapis.com/docs/cn/api-reference/models.md)和 API Key 权限. 模型名正确但文案提示暂不可用时, 稍后重试或联系支持 |
| `invalid_private_assets`, `invalid_image`, `invalid_image_file` | 素材引用无效, 图片无法解码, 数量或尺寸超限, 或链接无法读取 | 检查具体素材的位置和限制; 重新导出或上传后再提交 |
| `access_denied`, 或 HTTP 401/403 且无 code | API Key 无效, 过期, 停用, IP 或模型权限受限 | 检查 API Key 和访问权限. 不要把服务返回的认证错误一律理解为本地密钥错误 |
| `insufficient_user_quota`, `quota_not_enough`, `token_quota_not_enough`, `pre_consume_token_quota_failed` | 账户余额, 令牌可用额度或周期限额不足; 令牌额度检查也可能临时失败 | 只有文案明确指向本账户或令牌时才充值或调整额度. 服务侧额度问题或检查失败应稍后重试或联系支持 |
| `rate_limit_exceeded`, `RateLimitReached`, `rate_limit_unavailable` | 请求频率超限, 模型服务限流, 或暂时无法检查限额 | 降低并发, 优先遵守 `Retry-After`, 再使用带随机抖动的退避. 见[异步限流](https://docs.toapis.com/docs/cn/api-reference/rate-limits/async-tasks.md) |
| `get_channel_failed`, `all_channels_circuit_broken`, `provider_unavailable` | 当前模型暂时没有可用服务或负载过高 | 稍后重试; 持续失败时联系支持, 不需要修改图片内容 |
| `do_request_failed`, `first_output_timeout`, `up_timeout` | 连接, 等待首段输出或读取响应超时; 请求可能已被受理 | 有任务 ID 时先查询该任务; 无 ID 的视频请求按下方恢复流程处理 |
| `bad_response_status_code`, `bad_response`, `bad_response_body`, `read_response_body_failed`, `upstream_error`, `unknown_error` | 服务返回错误或响应无法读取, 解析 | 结合 HTTP 状态和文案判断. 先确认是否已有任务, 持续失败时提供请求 ID 联系支持 |
| `convert_request_failed`, `model_price_error`, `pricing_failed`, `pricing_unavailable`, `internal_error` | 请求转换, 定价或服务处理失败, 不一定是输入错误 | 文案有明确字段约束时修正输入; 否则稍后重试或联系支持 |
| `task_not_found`, `task_not_exist`, `request_not_found` | 任务或恢复记录不存在, 不属于当前账号, 或恢复记录已过期 | 核对 ID, 账号和查询入口. 恢复记录不存在不能证明原请求从未执行 |
| `invalid_client_request_id`, `request_cache_unavailable`, `submission_unconfirmed` | 恢复标识无效, 恢复服务不可用, 或提交结果尚未确认 | 修正标识格式, 或等待并查询原请求; 不要连续生成新 ID 重提 |
| `invalid_callback_url`, `callback_url_origin_mismatch`, `webhook_not_configured`, `webhook_configuration_invalid`, `webhook_configuration_unavailable`, `webhook_configuration_error`, `webhook_api_token_required` | 回调地址或 Token 的 Webhook 配置不满足要求, 或配置暂不可读取 | 按[任务 Webhook](https://docs.toapis.com/docs/cn/api-reference/webhooks/task-webhooks.md)检查 HTTPS 地址, 来源, API Token 和配置 |
| `sensitive_words_detected`, `prompt_blocked`, `content_policy_violation`, `content_filter`, `content_filtered` | 输入或生成结果未通过内容审核 | 检查提示词和全部参考素材, 修改合规内容后再提交; 不要自动重复原请求 |
| `invalid_encrypted_content` | 对话返回项中的加密内容无法验证或解析 | 检查客户端是否修改或截断了历史返回项, 保持此类项原样. 持续失败时联系支持, 不要尝试修改加密内容 |

## invalid\_request 可能具体指什么

以下情况来自实际请求和失败任务的诊断归纳. 它们可能由上述通用参数码包裹, 也可能以更具体的 `reason` 或模型原始错误码返回. **先看具体字段和说明, 再决定修改什么.**

| 具体情况 | 如何区分和修正 |
| - | - |
| 输出尺寸或比例写法不匹配 | 某些模型的 `size` 接受 `1:1` 等比例, 某些接受像素尺寸. 把 `1024x1024` 传给只接受比例的模型会失败. 按所选模型的 `size`, `resolution`, `aspect_ratio` 定义传值 |
| 宽高, 总像素或尺寸倍数不符合要求 | 图片可能太小, 太大, 比例过宽, 或宽高不是要求的倍数. 区分报错指向参考图还是输出尺寸, 按该模型限制缩放或裁剪; 不是所有模型都使用同一倍数或像素上限 |
| 参考图文件或图片数量超限 | 文件字节数, 长边像素, 总像素和图片数量是不同限制. 文件压缩只能减少字节数, 未必降低像素数. 根据报错选择压缩, 缩放或减少图片 |
| 图片字段类型错误 | 接口需要 URL 字符串数组时, 传入对象数组会解析失败. `image_urls` 与 `image_with_roles` 的结构不同, 某些入口也不接受 Base64 或混用两种字段 |
| URL 存在但服务读不到文件 | 403/404, 需要登录, 链接过期, 下载超时, 防盗链或返回 HTML 页面都可能失败. 提供足够长时间有效, 可直接下载真实文件的公网 URL, 或先使用[上传接口](https://docs.toapis.com/docs/cn/api-reference/uploads/images.md) |
| 素材格式或时长不满足要求 | 文件扩展名正确不代表内容可解码. GIF, 视频编码, 帧率, 单段或总参考时长可能不符合所选模型要求. 按模型文档重新导出媒体 |
| Seedance 任务类型与参数冲突 | 被识别为视频编辑时, 可能要求 `aspect_ratio=adaptive`, `duration=-1`; 延长任务也可能要求 `adaptive`. `InvalidParameter.TaskTypeConstraint` 也可能表示提示词和素材被识别成另一任务类型. 见[Seedance 2.5](https://docs.toapis.com/docs/cn/api-reference/videos/seedance-2-5/generation.md) |
| 文本, 对话历史或工具调用结构错误 | 提示词超长, 模型不接受 `developer` 角色, `tool_calls` 缺少对应工具回复, 或思考模式缺少必要的 `reasoning_content`. 按该模型协议修正历史结构 |
| 参数存在但当前模型不接受 | `quality`, `reasoning_effort`, `temperature`, `thinking`, `enable_thinking` 等取值或字段并非通用. `max_tokens` 与 `max_completion_tokens` 也可能互斥. 工具 Schema 和 `response_format` 需符合所选模型约束 |

历史失败中的具体数值不是全平台限制. 能否传图片要看模型是否支持该输入, 不能仅根据 `invalid_request` 或 `invalid_image` 推断.

## 任务失败原因速查

任务已返回 ID 后, 以查询状态为准. 普通生成任务失败常见 `error.code=generation_failed`, 具体分类读取可选的 `error.reason`. 以下标识是 reason, 不应假定它们都出现在请求错误的 code 字段.

若响应提供 `error.input_media_errors`, 逐项读取 `type`, `index`, `message`. 例如 `type=image`, `index=0` 指向原请求的第一张图片, 可以只修正该素材. 这些明细不是所有模型或查询格式都提供.

| error.reason | 可能的情况与处理 |
| - | - |
| `invalid_input`, `missing_parameter` | 输入未通过校验或缺少字段. 检查上方具体情况和错误文案, 修正后重新生成 |
| `reference_image_too_large`, `image_dimensions_multiple` | 参考图文件过大, 或图片尺寸不符合倍数要求. 分别检查文件大小和像素尺寸 |
| `reference_media_unreadable`, `unsupported_media_format` | URL 无法下载, 文件无效或格式不支持. 检查访问权限和真实媒体内容 |
| `unsupported_parameter_value`, `parameter_out_of_range`, `parameter_replacement_required` | 值不在允许集合或范围, 或需要替换字段. 根据返回文案和模型说明修改 |
| `video_edit_parameters_required`, `unsupported_request_capability` | 视频编辑参数组合不合法, 或模型不支持所请求能力. 调整任务类型, 参数或模型 |
| `content_policy_rejected` | 提示词, 参考图片/视频/音频, 或生成输出未通过安全或版权审核. 检查全部输入; 合规输入也可能因输出审核而失败 |
| `service_busy`, `request_rate_limited` | 服务繁忙或限流. 等待并降低请求频率 |
| `generation_timeout` | 等待生成或任务处理超时. 先确认已有任务状态, 不要在仍处理中时反复重新生成 |
| `generation_unavailable`, `model_unavailable`, `model_region_unavailable` | 当前模型服务暂不可用, 或当前访问区域不支持. 核对模型与权限, 持续异常时联系支持 |
| `insufficient_user_balance`, `token_quota_exceeded` | 本账户余额或 API Token 额度不足. 检查两者及周期限额后再提交 |
| `result_storage_failed` | 生成结果保存或交付失败, 不一定是生成模型不支持输入. 提供任务 ID 联系支持 |
| `submission_pending_reconciliation` | 提交或生成结果仍待核实. 保留已有 ID 并等待查询结果, 避免重复生成 |
| `refund_pending` | 失败任务退款尚在处理. 查看最新查询中的可用计费状态, 持续异常时联系支持 |
| `request_cancelled` | 请求或任务被取消. 确认取消是否符合预期后再决定重新提交 |
| `generation_failed`, `service_error` | 没有更具体的公开原因, 或服务内部处理失败. 保留任务和请求 ID, 联系支持 |

部分模型保留原始错误, 如 `InvalidParameter.TaskTypeConstraint`, `RateLimitReached`, `InputImageSensitiveContentDetected` 或 `OutputVideoSensitiveContentDetected`. 这些取值不是完整枚举, 分别可能涉及任务参数, 服务限流, 输入审核或输出审核.

Seedance Global 查询的 `error.code` 和 `error.message` 可能是原始 JSON 值, 包括数字或 `null`, 也可能缺省. OpenAI 视频格式和 Webhook 不保证提供 `reason`. 客户端应容忍未知码, 缺省字段和不同字段类型; 不要把原始数字 code 当作 HTTP 状态.

## 重试与请求恢复

* 参数, 格式和内容审核问题: 修改输入后再提交. 原样重试通常不能解决.
* 限流或暂时不可用: 有 `Retry-After` 时优先遵守; 否则使用指数退避和随机抖动, 避免无限重试.
* 已有任务 ID: 继续查询该任务, 或接收[任务 Webhook](https://docs.toapis.com/docs/cn/api-reference/webhooks/task-webhooks.md). `queued` 和 `in_progress` 不表示失败, 不要因此创建重复任务.
* 视频提交超时或返回 `submission_unconfirmed`: 如果原请求使用了 `client_request_id`, 用同一账号调用 `GET /v1/video/requests/{client_request_id}`. 得到 `task_id` 后查询任务; `submitting` 或 `unknown` 表示继续等待. 只有恢复记录明确为 `failed` 且 `error_code=submission_rejected` 时, 才表示该请求已被明确拒绝, 可按提示发起新请求. 此恢复能力只适用于支持并使用了该字段的视频入口, 不适用于所有 API.

失败任务不一定立即完成退款. 查询[计费状态](https://docs.toapis.com/docs/cn/api-reference/account/pricing.md)中的可用 `billing` 字段; 字段缺省不代表免费或退款完成. Webhook 是事件快照, 不保证与后续查询的计费字段完全相同.

## 联系支持时提供什么

提供请求时间和时区, 模型名, 接口路径, HTTP 状态, 请求 ID, 可用的任务 ID, 错误 code/reason 和脱敏后的具体说明. 图片问题附上尺寸, 格式和文件大小即可. 不要提供 API Key, 签名 URL, 完整提示词或私人素材; 需要复现时使用可公开的最小示例.


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