错误
每个端点都以相同方式失败：一个 HTTP 状态码和一个 JSON 信封。
{
"error": {
"type": "invalid_request",
"code": "invalid_input",
"message": "duration must be one of 5, 10.",
"param": "duration",
"details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
"request_id": null,
"doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
}
}| 字段 | 含义 |
|---|---|
type |
错误的大类。根据此字段决定如何处理。 |
code |
具体原因，稳定且可供机器读取。每个代码都有下文对应的章节；doc_url 链接到该章节。 |
message |
面向人类的说明，可安全地记录日志或展示给开发者。 |
param |
出错的输入参数或请求头（如果有）。 |
details |
对于输入错误，列出发现的每个问题：[{ "param", "message" }]。 |
request_id |
相关请求（如果存在）。 |
返回错误的调用不会收取任何费用。接受后才失败的请求会保持 failed 状态，在请求对象中携带 error: { "type", "code", "message" }，并自动退款。
类型
| 类型 | HTTP 状态 | 处理方式 |
|---|---|---|
invalid_request |
400、413 或 422 | 修正请求。重试相同调用仍会失败。 |
authentication_error |
401 | 在 Authorization: Bearer <key> 中发送有效密钥。 |
permission_error |
403 | 使用具有所需 scope 的密钥。 |
not_found |
404 | 检查模型 id 或请求 id。 |
insufficient_credits |
402 | 为 API 余额充值（错误中的 top_up_url）。 |
budget_exceeded |
402 | 该密钥自己的预算已用尽。最终处理方式：请求密钥所有者提高预算。 |
conflict |
409 | 资源当前状态不允许此调用。 |
rate_limited |
429 | 等待 Retry-After 秒后重试。 |
upstream_error |
502 | 模型后端失败。可以使用相同的 Idempotency-Key 安全重试：请求会再次运行，且不会收费。 |
service_unavailable |
503 | API 已暂停或某个依赖服务不可用。稍后重试。 |
internal_error |
500 | 我们的程序错误。重试；如果持续发生，请提供时间和 request_id 联系支持。 |
代码
invalid_request
通用的格式错误请求（400）。
invalid_json
请求正文不是有效的 JSON（400）。
invalid_body
请求正文是有效 JSON，但不是对象；模型输入必须是 JSON 对象（400）。
body_too_large
请求正文大于 16 MB（413）。请上传大文件并改为传入其 URL（参见 文件）。
invalid_parameter
查询参数的值错误，例如 limit 不在 1 到 100 之间、wait 不是数字、未知的 status 或 category，或者 storage 不是 permanent / temporary（400）。param 会指出该参数。
invalid_category
GET /openapi.json?category= 指定了不存在的类别（400）。GET https://api.doitong.com/v1/categories 会列出类别。
invalid_cursor
列表调用中的 cursor 不属于此列表（400）。请不带 cursor 重新开始。
invalid_idempotency_key
Idempotency-Key 请求头为空或超过 255 个字符（400）。
invalid_arguments
MCP 工具调用缺少参数或参数格式错误（仅限 MCP）。param 会指出该参数。
invalid_input
模型输入未通过验证（422）：未知参数（消息会建议最接近的有效名称）、缺少必需参数、类型错误、值不在允许的列表或范围内，或同时提供了规范名称和原生名称但值不同。param 是第一个出错的参数，details 列出所有出错参数。不收取任何费用。
unsupported_file
文件类型不受支持（422），例如上传了不支持的扩展名，或 content_type 与扩展名不匹配。
invalid_webhook_url
webhook_url 不是公开的 https:// URL（422）。拒绝私有地址、本地地址和普通 http:// 地址。
missing_api_key
该端点需要 API 密钥，但请求未发送密钥（401）。
invalid_api_key
密钥未知、已撤销或已过期（401）。
insufficient_scope
密钥缺少此调用所需的 scope（403），例如运行所需的 models:run，或读取请求和余额所需的 models:read。参见 身份验证。
account_disabled
账户已关闭或暂停（403）。其密钥不再有效。
not_found
路径不存在（404）。
model_not_found
不存在具有此 id 的公开模型（404）。使用 GET https://api.doitong.com/v1/models 列出模型。
request_not_found
账户中不存在具有此 id 的请求（404）。其他账户的请求永远不可见。
insufficient_credits
账户的 API 余额（API 积分，1,000 API 积分 = $1 —— 不包括 Doitong 应用的积分）不足以支付此次调用的价格（402）。响应会在扣费前发送。错误中包含 top_up_url；请在 https://doitong.com/developers/dashboard#balance 充值后重试。
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
"message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
"top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }budget_exceeded
此次调用将超过 API 密钥自己的 API 积分预算（402）。预算由密钥所有者设置；在其提高预算前，重试无效。
conflict
调用与资源当前状态冲突（409）。
idempotency_mismatch
Idempotency-Key 已用于不同的正文（409）。新操作请使用新密钥。
idempotency_in_progress
具有相同 Idempotency-Key 的请求正在创建中（409）。稍后片刻重试即可获取该请求。
request_active
请求仍处于 queued 或 running 状态，因此还没有可删除的文件（409）。请求完成后再删除文件。
not_cancelable
请求已经 succeeded 或 failed，无法取消（409）。
rate_limited
密钥在当前时间窗口内发送了过多请求（429）。参见 X-RateLimit-* 和 Retry-After 请求头。
too_many_inflight
账户已有 10 个处于 queued 或 running 状态的请求（429）。其中一个完成后再启动下一个。
upstream_error
模型后端拒绝或未能处理请求（运行时为 502，或请求以此代码结束并处于 failed 状态）。API 积分会退款。如果后端本身拒绝了输入，调用会返回带有其消息的 422 invalid_input。
upstream_lost
模型后端不再识别该请求，因此不会有结果返回。请求会以此代码结束为 failed（类型为 upstream_error）并退款。请重新运行。
timeout
请求运行时间超过限制（图像 15 分钟、视频 60 分钟、其他情况 30 分钟）并被停止。请求会以此代码结束为 failed 并退款。
service_unavailable
API 暂时暂停，或文件上传等依赖服务不可用（503）。稍后重试。
internal_error
我们这边发生了故障（500）。重试；如果持续发生，请联系支持。
charge_failed
由于内部问题，无法向账户扣费（500）。请求会标记为 failed；不会扣款。请重试。
pricing_unavailable
模型未配置价格，因此当前无法报价或运行（500）。