Claude API 接入与错误速查
Claude API / Anthropic API 的基础接入、必需请求头、常见错误类型、请求大小限制、streaming、batch、529、429 和排查建议。
| 项目 | 应该怎么填 | 排查重点 |
|---|---|---|
| Base URL | https://api.anthropic.com | 直连 Claude API / Anthropic API 使用这个主机。 |
| Messages API | POST /v1/messages | 多数聊天、生成、工具调用场景从 Messages API 开始。 |
| Message Batches API | POST /v1/messages/batches | 大量异步任务；官方说明可降低 50% 成本，但不是实时返回。 |
| Token Counting API | POST /v1/messages/count_tokens | 发送前估算 token，用来控制成本、上下文和限流风险。 |
| Models API | GET /v1/models | 列出可用模型和模型详情，避免写死旧模型名。 |
| 认证 | credential header | 401 通常先检查凭证、代理转发和工作区。 |
| 版本头 | anthropic-version: 2023-06-01 | 所有请求必需；缺失或错误版本头会导致校验失败。 |
| Content-Type | application/json | JSON 请求必需；正文应为合法 JSON，并匹配模型参数要求。 |
| 请求追踪 | request-id / request_id | 报障、查日志、找平台支持时保留请求 ID。 |
| 长请求 | streaming 或 Message Batches | 预计超过数分钟的非流式请求容易被网络或 SDK 超时影响。 |
| HTTP | error.type | 含义 | 先检查什么 |
|---|---|---|---|
400 | invalid_request_error | 请求格式、参数或正文不合法。 | 校验 JSON、model、messages、max_tokens、tool 参数。 |
400 | invalid_request_error | 新模型不支持预填 assistant 消息。 | 不要把最后一条 assistant 作为 prefill；改用结构化输出、system 或 output_config。 |
401 | authentication_error | 认证失败。 | 检查凭证、代理转发和工作区。 |
402 | billing_error | 账单或付款问题。 | 检查 Console 账单、额度、Marketplace 订阅状态。 |
403 | permission_error | 无权访问对应资源。 | 检查工作区、模型权限、文件或资源 ID 权限。 |
404 | not_found_error | 资源不存在。 | 检查 endpoint、model、file、batch、message id。 |
413 | request_too_large | 请求超过大小限制。 | 压缩输入、拆分请求、改用 Batch 或 Files。 |
429 | rate_limit_error | 触发速率限制或加速限制。 | 指数退避、降低并发、逐步爬坡、查看组织限额。 |
500 | api_error | 服务端错误。 | 带 request-id 重试或记录后排查。 |
504 | timeout_error | 处理超时。 | 长请求优先使用 streaming 或 Message Batches。 |
529 | overloaded_error | Anthropic 服务临时高负载。 | 指数退避后重试；这类错误可能由全站流量造成。 |
| API | 上限 | 备注 |
|---|---|---|
| Messages API | 32 MB | 普通消息请求；超过可能直接返回 413。 |
| Token Counting API | 32 MB | 计数请求。 |
| Message Batches API | 256 MB | 适合更大的异步批量任务。 |
| Files API | 500 MB | 文件上传场景。 |
| Sessions / Agents / Environments | 32 MB | 相关容器与会话类接口。 |
- 社区常见问题集中在 429、529、streaming、长请求超时、assistant prefill、请求过大和 request_id 定位。
- 流式响应使用 SSE，可能在初始 200 之后才返回流内错误，所以客户端要处理 stream event error。
- 长时间请求建议开启 streaming；非常长的任务优先考虑 Message Batches，避免非流式连接超时。
- 429 可能来自普通速率限制，也可能来自组织级加速限制；新流量不要突然大幅拉高。
- 529 是服务端高负载，不等于模型拒答；退避重试时要避免所有 worker 同时重试造成雪崩。
- 错误响应通常包含顶层 type、error.type、error.message 和 request_id；响应头也有 request-id，保存它对定位问题很有用。
- 新模型不支持 assistant prefill；不要用最后一条 assistant 消息预填输出。
来源：Anthropic 官方 API 文档、错误文档、Claude 官方价格页，以及社区常见排查问题整理。本站只把社区问题作为选题线索；接口、模型、限额与计费事实以官方文档和控制台为准。
这是一张 Claude API 接入和 Anthropic API 错误码速查表，适合排查 Claude API authentication_error、rate_limit_error、request_too_large、overloaded_error、timeout_error、prefill 不兼容、streaming 200 后失败、长请求超时和 request_id 定位等常见问题。
相关搜索场景： Claude API 接入 · Anthropic API 错误码 · Claude API 报错 · Claude Messages API · anthropic-version header · Claude API 401 · Claude API 429 · Claude API 529 · authentication_error · rate_limit_error · overloaded_error · request_too_large · Claude API request-id · Claude API timeout · Claude API rate limit · Claude API prefill not supported · Claude streaming error
FAQ
Claude API 最少需要哪些请求头？
直连 Anthropic API 时通常需要认证凭证、anthropic-version，以及 JSON 请求的 content-type: application/json。401 先检查凭证是否属于正确 workspace，代理是否丢头。
429 和 529 有什么区别？
429 多数表示你的组织或请求模式触发限流或加速限制；529 表示 Anthropic 侧临时高负载。两者都应做退避重试，但 429 还要检查限额、并发和流量爬坡。
529 overloaded_error 是不是模型拒绝回答？
不是。529 是服务端过载或容量问题，应该记录 request-id、做指数退避和抖动重试；不要把它当成安全拒答或 prompt 问题处理。
为什么明明 HTTP 200，流式调用还会失败？
SSE 流式响应可能在连接建立后返回流内错误，客户端必须监听并处理 event error，而不是只看初始 HTTP 状态码。
Prefilling assistant messages is not supported 怎么处理？
这是 400 invalid_request_error。不要用最后一条 assistant 消息预填新模型输出，改用 structured outputs、system 指令或 output_config。
多轮工具调用为什么会突然 400？
常见原因是把上一轮模型返回的内部状态类内容过滤、重排或重建了。代理层、日志清洗层和消息压缩层都要确认不会改写模型返回的特殊内容块。
请求太大应该怎么处理？
先减少上下文、拆分消息或压缩输入；批量或大文件场景考虑 Message Batches API 或 Files API。不要只提高 max_tokens，它解决不了请求体过大。
非流式长请求超时怎么办？
预计长时间运行时使用 streaming；超过数分钟或批量任务优先用 Message Batches，通过轮询结果降低网络中断风险。
request_id 应该记录在哪里？
记录在应用日志、错误上报和用户可复制的诊断信息里。遇到 500、529、超时或平台支持排查时，request_id 通常比完整 prompt 更安全、更有用。
Batch API 适合替代实时聊天吗？
不适合。Batch 适合离线、大量、可等待的任务；实时聊天、交互式工具调用和需要立刻返回的用户请求仍应走普通 Messages API。