# 错误

每个端点都以相同方式失败：一个 HTTP 状态码和一个 JSON 信封。

```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（参见 [文件](https://doitong.com/developers/docs/files)）。

### `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`。参见 [身份验证](https://doitong.com/developers/docs/authentication#scopes)。

### `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](https://doitong.com/developers/dashboard#balance) 充值后重试。

```json
{ "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）。