错误

何时阅读本页复制链接

请求失败了，你想知道原因、是否应该重试，或者联系支持时要提供什么。各项限制和退避策略见速率限制。

错误格式复制链接

错误使用你所调用的 API 的格式，两种格式下的 HTTP 状态码相同。

/v1/*（Anthropic 格式）：

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: anthropic/no-such-model"
  },
  "request_id": "0b1c6f2e-5d4a-4f7e-9a51-3f0e8d2c7b19"
}

/openai/v1/*（OpenAI 格式）：

{
  "error": {
    "message": "The model `anthropic/no-such-model` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Anthropic 和 OpenAI SDK 会把这些错误转换成各自的错误类（例如 NotFoundError），所以你很少需要自己解析。错误处理示例见 curl、Node.js 或 Python。

状态码复制链接

在 Anthropic 格式返回 529 的情况下，兼容 OpenAI 的 API 返回 503，因为 OpenAI 客户端不认识 529。它针对模型返回的 404 还会设置 "param": "model"。

这些错误都不计费。见计费方式。

可能看到的消息复制链接

由模型本身返回的 400（例如模型不接受某个参数）带有模型自己的消息。

不存在的路径复制链接

网关不提供的路径，例如 /v1/messages/batches 或 /v1/files，会返回简单格式的 404，不使用上面任何一种错误格式：

{ "statusCode": 404, "message": "Cannot POST /v1/messages/batches" }

流式输出中的错误复制链接

流式响应一旦开始，HTTP 状态码就已经是 200。如果之后出错，网关会发送一个错误事件，然后结束流。这个请求在用量中标记为 失败，且不计费。

Anthropic 格式：一个 error 事件，之后没有 message_stop。

event: error
data: {"type":"error","error":{"type":"api_error","message":"Upstream provider error"}}

OpenAI 格式：一个带 error 对象的 chunk，然后是 [DONE]。

data: {"error":{"message":"Upstream provider error","type":"server_error","param":null,"code":null}}

data: [DONE]

错误类型与上表相同。Anthropic 和 OpenAI SDK 读到它时会抛出 APIError（或其子类），且不会重试：如果需要，请自己重新发送请求。

如果客户端在流式输出中途断开连接，不会有错误事件；见中断的流式输出。

请求 id复制链接

有两个响应头用于标识请求：

• 在 Anthropic 格式中，错误体里的 request_id 就是 x-request-id。
• 在兼容 OpenAI 的 API 上，completion 的 id 是 chatcmpl- 加上它的 request-id。
• Anthropic SDK 提供 request-id（message._request_id，以及 Python 中的 error.request_id 或 Node 中的 error.requestID）。被拒绝的请求没有 request-id，所以要从错误的响应头中读取 x-request-id。
• OpenAI SDK 提供 x-request-id（completion._request_id，Python 中的 error.request_id，Node 中的 error.requestID）。

联系支持复制链接

发邮件至 support@ezat.io，并附上：

1. request-id（如果响应中有）和 x-request-id。
2. 请求的时间（注明时区）、模型，以及你调用的是哪个 API（/v1/messages 或 /openai/v1/chat/completions）。
3. HTTP 状态码和错误的 message。

切勿发送你的 API key。请求和响应的内容不会被保存，所以请附上请求中相关的部分。

给 AI agent 的说明复制链接

1. 先看 HTTP 状态码，再看 error.type（Anthropic 格式）或 error.code（OpenAI 格式）。
2. 不要重试 400、401、402、403、404 或 413。修正请求，告诉用户检查 key 或在 https://router.ezat.io/zh/billing 充值，或者从 GET https://api.router.ezat.io/v1/models 中选择模型。
3. 对 429、500、529 和 503 使用指数退避重试；有 retry-after 响应头时，至少等待它给出的秒数。官方 Anthropic 和 OpenAI SDK 已经这样做了，默认重试两次。
4. 对于 504 timeout_error，加上 "stream": true 重新发送，而不是原样重试。
5. 在返回 200 之后，流仍可能以一个 error 事件（Anthropic）或 error chunk（OpenAI）结束。按 500 处理。
6. 报告问题时，把 request-id 和 x-request-id 响应头以及请求时间提供给用户。切勿包含 API key。