5.7 KiB
错误、限流与超时对照
来源：
- 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-afterheader。
对中转站的含义：
- 网关自身的上游超时不能小于客户端预期，否则长任务永远失败。
- 网关到上游、客户端到网关，两段都需要 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 空行）文档未说明。