错误、限流与超时对照

来源：

https://platform.claude.com/docs/en/api/errors

https://api-docs.deepseek.com/quick_start/error_codes

OpenAI OpenAPI spec（错误页面未单独抓取，见文末"待补"）

采集于 2026-08-12。

1. HTTP 状态码对照

状态码	Anthropic	DeepSeek	说明
400	`invalid_request_error`	请求体格式非法	Anthropic 也用它兜底其他未列出的 4xx
401	`authentication_error`	API key 错误	Anthropic 上也可能是 key 过期/吊销，或 AWS 凭证/SigV4 问题
402	`billing_error`	余额不足	OpenAI 无此码
403	`permission_error`	—	key 无权限访问该资源
404	`not_found_error`	—
409	`conflict_error`	—	资源并发修改/唯一值冲突
413	`request_too_large`	—	见 §2
422	—	参数非法	Anthropic/OpenAI 不用 422，DeepSeek 用
429	`rate_limit_error`	限流
500	`api_error`	服务端故障
503	—	服务器过载
504	`timeout_error`	—	建议改用流式
529	`overloaded_error`	—	Anthropic 专有，全平台高负载

中转站的映射决策点

**402（余额不足）**没有 OpenAI 对应码。可选：透传 402、或映射为 429 + insufficient_quota 类型（OpenAI 生态的惯例是 429）。
529 对 OpenAI 客户端是未知码，多数 SDK 不会自动重试。建议映射为 503。
422 对 OpenAI 客户端也不常见，建议映射为 400。
Anthropic 的 429 有两种成因：常规限流，以及用量突增触发的加速度限制（acceleration limit）。后者的解决办法是"逐步爬坡、保持稳定用量"，不是简单退避重试。

2. 请求体积上限（Anthropic）

端点	上限
Messages API	32 MB
Token Counting API	32 MB
Batch API	256 MB
Files API	500 MB

超限返回 413。在直连 Claude API 时，这个错误由 Cloudflare 在到达 API 服务器之前返回——意味着响应体格式可能不是标准的 Anthropic 错误 JSON。中转站的错误解析需要能容忍非 JSON 的 413 响应。

3. 错误响应体

Anthropic

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

error.type 的取值集合会随时间扩充（versioning policy 明确说明），解析器必须能处理未知 type。

流式中途错误（Anthropic）

HTTP 已经返回 200 之后，错误以 SSE 事件形式发出：

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

中转站必须处理这种情况：此时已经无法改 HTTP 状态码，只能在下游流中也以某种方式表达错误。OpenAI SSE 格式没有标准的错误事件——常见做法是发一个带 error 字段的 data chunk，然后 [DONE]。

4. Request ID

Anthropic 每个响应都带 request-id header（形如 req_018EeWyXxfu5pfWkrYcMdjWG），错误体里也有 request_id 字段。

在 AWS 上的 Claude Platform 会有两个 ID：x-amzn-requestid（主，CloudTrail 索引）和 request-id（次，Anthropic 支持工单用）。

中转站建议：生成自己的 gateway request id，并在响应 header 中同时保留上游的 ID，便于排障。

5. 超时与长请求

Anthropic 侧的明确约束：

官方 SDK 会校验非流式 Messages 请求预期不超过 10 分钟，超过则拒绝发出。
超过 10 分钟的请求应改用流式或 Batch API。
部分网络会在空闲一段时间后断开连接，导致请求超时且拿不到响应。官方建议直连集成时设置 TCP socket keep-alive。
SDK 默认对瞬时失败（连接错误、限流、5xx）指数退避重试 2 次，并遵守 retry-after header。

对中转站的含义：

网关自身的上游超时不能小于客户端预期，否则长任务永远失败。
网关到上游、客户端到网关，两段都需要 keep-alive 配置。
大 max_tokens 的非流式请求是最容易踩超时的场景，建议在网关侧自动转成流式再聚合（Anthropic SDK 的 get_final_message() 就是这个思路）。

6. 限流 header

Anthropic OpenAI 兼容层确认支持全套：

x-ratelimit-limit-requests
x-ratelimit-limit-tokens
x-ratelimit-remaining-requests
x-ratelimit-remaining-tokens
x-ratelimit-reset-requests
x-ratelimit-reset-tokens
retry-after

中转站若做自己的配额管理，应该合成这套 header 返回给下游（而不是透传上游的，因为上游额度和下游用户额度不是一回事）。

7. 用户级限流隔离

Provider	字段	约束
OpenAI	`safety_identifier`（`user` 已废弃）	≤64 字符，建议传 hash
OpenAI	`prompt_cache_key`	用于提升缓存命中，与 safety_identifier 分离
Anthropic	`metadata.user_id`
DeepSeek	`user_id`	≤512 字符，仅 `[a-zA-Z0-9\-_]`

注意 DeepSeek 的字符集限制比另外两家严格——直接透传 OpenAI 的 safety_identifier（可能含其他字符）会被拒。

8. 待补

OpenAI 的错误码/错误体规范未单独收集。platform.openai.com/docs/guides/error-codes 未抓取（主站 403）。需要补充：insufficient_quota、context_length_exceeded、invalid_api_key 等 error.code 取值，以及 OpenAI 错误体的 {error: {message, type, param, code}} 结构细节。
DeepSeek 限流时的连接层行为（是否发 keep-alive 空行）文档未说明。

5.7 KiB Raw Blame History Unescape Escape