143 lines
5.7 KiB
Markdown
143 lines
5.7 KiB
Markdown
# 错误、限流与超时对照
|
||
|
||
> 来源：
|
||
> - 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
|
||
|
||
```json
|
||
{
|
||
"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 空行）文档未说明。
|