# API 错误

本页面提供所有 Interactions API 错误代码的参考，描述错误响应格式，并解释 API 如何针对不同请求类型传递错误。

## 标准 API 错误代码  {% #api-error-codes %}

这些通用请求级错误代码对应于标准 HTTP 状态代码。使用 `code` 应用程序逻辑中的字段以编程方式处理错误。

| 代码                    | HTTP 状态       | 说明                                      | 建议采取的行动                                                                                                  |
| --------------------- | ------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `invalid_request`     | 400 错误请求      | 请求负载格式错误或包含无效参数。                        | 检查您的请求语法和参数 [API参考](/api-reference/interactions-api).                                                    |
| `failed_precondition` | 400 错误请求      | 由于不满足先决条件（例如禁用计费），因此无法处理请求。             | 验证项目计费状态或帐户先决条件。                                                                                         |
| `out_of_range`        | 416 请求的范围无法满足 | 请求参数超出有效范围。                             | 检查参数值和限制。                                                                                                |
| `parameter_unknown`   | 400 错误请求      | 该请求包含未知参数。                              | 删除无法识别的参数并重试。                                                                                            |
| `authentication`      | 401 未经授权      | API 密钥丢失、无效或过期。                         | 验证您的 [API 密钥](/docs/api-key).                                                                            |
| `payment_required`    | 402 需要付款      | 您的预付款信用余额已耗尽。                           | [添加制作人员](/docs/billing#buy-credits) 到您的结算帐户，或打开 [自动重新加载](/docs/billing#auto-reload)。不要重试：在添加积分之前请求不会成功。  |
| `permission_denied`   | 403 禁止        | 您的 API 密钥缺少此资源的权限，或者您的项目受到限制或需要验证或计费更改。 | 检查您的 API 密钥权限， [验证状态](/docs/verification)和计费状态。参见 [项目受限或不可用](/docs/troubleshooting#project-unavailable). |
| `not_found`           | 404 未找到       | 未找到请求的资源。                               | 验证资源路径和参数。                                                                                               |
| `model_not_found`     | 404 未找到       | 未找到指定型号。                                | 验证型号名称或回退到其他型号。                                                                                          |
| `already_exists`      | 409 冲突        | 您尝试创建的实体已存在。                            | 重新创建之前检查资源是否已存在。                                                                                         |
| `aborted`             | 409 冲突        | 由于冲突或并发检查失败，操作被中止。                      | 在更高的应用程序级别重试该请求。                                                                                         |
| `rate_limit_exceeded` | 429 请求过多      | 您已超出每分钟或每秒请求或 token 限制。                 | 等待并使用指数退避重试。                                                                                             |
| `quota_exceeded`      | 429 请求过多      | 您已超出每日配额。                               | 等待配额重置或请求增加配额。                                                                                           |
| `too_many_requests`   | 429 请求过多      | 您在短时间内提出了太多的要求。                         | 等待并使用指数退避重试。                                                                                             |
| `cancelled`           | 499 客户端关闭请求   | 客户端在请求完成之前取消了请求。                        | 无需采取任何行动。这通常意味着客户端已断开连接。                                                                                 |
| `api_error`           | 500 内部服务器错误   | 服务器发生意外错误。                              | 重试请求。如果问题仍然存在，请联系支持人员。                                                                                   |
| `unimplemented`       | 501 未实施       | 未实现或不支持该操作或功能。                          | 检查 API 功能或切换到支持的功能。                                                                                      |
| `service_unavailable` | 503服务不可用      | 服务暂时超载或停机。                              | 等待并使用指数退避重试。                                                                                             |
| `deadline_exceeded`   | 504 网关超时      | 该请求未在截止日期内完成。                           | 删除或增加客户端截止时间设置以使用服务器默认值。                                                                                 |

{% callout type="note" %}
上面未列出的任何错误代码都会回退到 `snake_case` HTTP 状态的版本。
{% /callout %}

## 生成阻塞代码  {% #generation-blocked-codes %}

这些错误代码表明策略、安全或内容限制阻止了模型的输出。当您收到这些代码之一时，请修改您的输入并重试。

| 代码                         | 说明                |
| -------------------------- | ----------------- |
| `safety`                   | 安全违规（有害内容）阻止了该请求。 |
| `recitation`               | 版权或引用限制阻止了该请求。    |
| `language`                 | 不支持的语言阻止了该请求。     |
| `prohibited_content`       | 禁止内容指南阻止了该请求。     |
| `spii`                     | 敏感个人身份信息限制阻止了该请求。 |
| `blocklist`                | 阻止列表上的禁止术语阻止了该请求。 |
| `image_safety`             | 安全违规阻碍了图像生成。      |
| `image_prohibited_content` | 禁止内容指南阻止了图像生成。    |
| `image_recitation`         | 版权或引用限制阻碍了图像的生成。  |
| `image_other`              | 未指定的原因阻止了图像生成。    |
| `content_blocked`          | 未指定的策略原因阻止了该请求。   |

## 生成错误代码  {% #generation-error-codes %}

这些错误代码表示模型生成的输出存在结构问题（例如格式错误的函数调用或未声明的工具调用）。

| 代码                          | 说明                    |
| --------------------------- | --------------------- |
| `malformed_function_call`   | 该模型生成了无法解析的函数调用。      |
| `malformed_tool_call`       | 该模型生成了无法解析的工具调用。      |
| `unexpected_tool_call`      | 该模型调用了请求中未声明的工具。      |
| `no_image`                  | 该模型无法生成图像。            |
| `too_many_tool_calls`       | 该模型生成的工具调用数量超出了允许的数量。 |
| `missing_thought_signature` | 响应缺少所需的思想签名。          |

## 错误响应格式  {% #error-schema %}

来自 Interactions API 的所有错误都会返回 `error` 对象包含一个 `code` 和 `message`。例如，传递不支持的工具类型会返回：

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
```

| 领域        | 类型  | 说明                      |
| --------- | --- | ----------------------- |
| `code`    | 字符串 | 机器可读的错误代码 `snake_case`. |
| `message` | 字符串 | 人类可读的错误描述。              |

## 错误是如何传递的  {% #error-delivery %}

根据您发出标准 HTTP 请求还是流式 (SSE) 请求，API 会以不同方式传递错误。

### 标准 HTTP 请求  {% #http-errors %}

对于标准（非流）请求，API 设置 HTTP 响应状态代码（例如 `400 Bad Request`, `401 Unauthorized`, 或 `429 Too Many Requests`）并返回一个 `error` JSON 响应正文中的对象：

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}
```

### 流式传输 (SSE) 请求  {% #sse-errors %}

对于流请求（`stream: true`），API 通过服务器发送事件 (SSE) 流发送错误事件 `event_type` 设置为 `"error"`。的 `error` 字段包含相同的 `code` 和 `message` 结构：

```json
{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}
```

有关完整的 SSE 事件架构，请参阅 [Interactions API 参考](/api-reference/interactions-api).

## 后续步骤  {% #whats-next %}

* [API 故障排除](/docs/troubleshooting)：解决常见问题和错误场景。
* [速率限制](/docs/rate-limits)：了解请求限制和配额处理。
