企业官网建设流程全解析

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体

本篇指南以仓库内置的 Claude API 技能文档 error-codes.md 为骨架，系统讲解 Claude API（Anthropic Messages API）返回的各类 HTTP 错误码：从 400 请求格式错误到 529 服务过载，逐一说明常见成因、排查思路与修复方案，并延伸到官方 SDK 的 typed exception 体系、自动重试策略与自定义指数退避实现。读完你可以准确判断一次 API 调用失败属于"客户端可修复"还是"服务端需等待"，并写出健壮、可长期维护的错误处理代码。

该文档是仓库内置的claude-api技能（SKILL.md）的共享参考文件之一，在技能使用说明中被列为"调试 HTTP 错误或实现错误处理时必读"的第 9 号文档。Warp 本身是一个从终端生长出来的 Agentic 开发环境，其内置技能库将这份错误码参考与各语言 SDK 文档（python、typescript、go、java、ruby、csharp、php、curl）配套使用，供开发者在构建 Claude API 应用时快速查阅。

一、错误码总览：一张表看懂 8 种核心错误

Claude API 的错误响应遵循统一结构：外层是type: "error"，内层error对象携带type与message，并附带request_id用于向服务方反馈问题。不同错误码的"可否重试"属性差异很大，这是设计错误处理逻辑时的第一判断依据：

规律一目了然：4xx 中除了 429 均不可重试（重试只会重复同样的错误、浪费配额），5xx 与 429 可安全重试。这正好对应 SDK 内置自动重试策略的设计——它只对 429 与 5xx 做指数退避重试，对 4xx 客户端错误直接抛出。

二、客户端错误详解（400 / 401 / 403 / 404 / 413）

400 Bad Request：请求结构不合法

常见成因：

• 请求体 JSON 格式错误（malformed JSON）
• 缺少必填参数：model、max_tokens、messages
• 参数类型错误（如应为整数却传了字符串）
• messages数组为空
• messages中 user / assistant 角色未交替排列

典型错误响应示例：

{ "type": "error", "error": { "type": "invalid_request_error", "message": "messages: roles must alternate between \"user\" and \"assistant\"" }, "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy" }

修复思路：发送前校验请求结构，逐项确认：

• model是合法模型 ID（必须是完整字符串，严禁追加日期后缀，例如用claude-sonnet-4-5而不是claude-sonnet-4-5-20250514，否则会得到 404）
• max_tokens为正整数
• messages数组非空，且角色严格交替

401 Unauthorized：认证失败

常见成因：

• 缺少x-api-key请求头或Authorization请求头
• API key 格式非法
• API key 已被撤销或删除

修复思路：确认ANTHROPIC_API_KEY环境变量已正确设置，且请求携带的是该环境变量的值而非硬编码在代码里的明文（把 key 写进代码本身就是常见的安全事故，见下文"常见错误速查表"）。

403 Forbidden：权限不足

常见成因：

• API key 无权访问所请求的模型
• 组织层面的限制（organization-level restrictions）
• 未获得 beta 功能访问权限却尝试调用 beta 接口

修复思路：在 Console 中检查 API key 的权限范围，必要时更换 key 或单独申请特定功能的访问权。

404 Not Found：模型或端点不存在

常见成因：

• 模型 ID 拼写错误（例如把claude-sonnet-4-6误写成claude-sonnet-4.6）
• 使用了已废弃的模型 ID（retired model）
• API 端点路径错误

修复思路：一律使用模型文档中的精确 ID；官方提供别名（alias），例如claude-opus-4-7。仓库内的 models.md 记录了完整模型 ID 与能力清单，model-migration.md 则整理了已退役模型的替换对照表（例如claude-3-5-sonnet-20241022退役后应替换为claude-sonnet-4-6），升级代码前建议先查阅。

413 Request Too Large：请求体超限

常见成因：

• 请求体超过接口允许的最大尺寸
• 输入 token 数量过多
• 图片数据过大

修复思路：减小输入规模——截断会话历史、压缩/缩放图片，或将大文档拆分后分批发送。

三、400 参数校验错误：最容易踩坑的一类

部分 400 错误专门来自参数校验，典型场景：

• max_tokens超过该模型上限
• temperature取值非法（合法范围 0.0–1.0）
• 扩展思考模式下budget_tokens>=max_tokens
• 工具（tool）定义 schema 非法

Opus 4.7 专属的模型级 400

在 Claude Opus 4.7 上，以下参数已彻底移除，只要发送就会返回 400：

• temperature、top_p、top_k全部移除——删除该参数即可；详细的各 SDK 语法迁移参考见 model-migration.md 中的 "Per-SDK Syntax Reference" 一节
• thinking: {type: "enabled", budget_tokens: N}已移除——改用thinking: {type: "adaptive"}

旧型号（Opus 4.6 及更早）扩展思考的经典错误

在仍支持budget_tokens的老型号上，最常见的低级错误是预算不小于输出上限：

# Wrong: budget_tokens must be < max_tokens thinking: budget_tokens=10000, max_tokens=1000 → Error! # Correct thinking: budget_tokens=10000, max_tokens=16000

注意：在 Opus 4.6 / Sonnet 4.6 上，budget_tokens虽然仍可用但已被标记为弃用（deprecated），仅作为迁移期的过渡手段保留；新代码应直接使用thinking: {type: "adaptive"}自适应思考。而在 Opus 4.7 上budget_tokens则是完全删除，没有过渡通道。

四、429 Rate Limited：限流与配额耗尽

常见成因：

• 超过每分钟请求数限制（RPM）
• 超过每分钟 token 数限制（TPM）
• 超过每日 token 数限制（TPD）

需要检查的响应头：

• retry-after：建议等待的秒数
• x-ratelimit-limit-*：当前配额上限
• x-ratelimit-remaining-*：剩余配额

修复思路：Anthropic 官方 SDK 会自动对 429 与 5xx 做指数退避重试（默认max_retries=2）。如果需要自定义重试行为（例如更长的退避、更强的抖动），参考各语言的错误处理示例。仓库内 python/claude-api/README.md 的 "Error Handling" 一节给出了读取retry-after头的示范代码：

except anthropic.RateLimitError as e: retry_after = int(e.response.headers.get("retry-after", "60")) print(f"Rate limited. Retry after {retry_after}s.")

五、服务端错误详解（500 / 529）

500 Internal Server Error

常见成因：

• Anthropic 服务端临时故障
• API 处理链路内部缺陷

修复思路：指数退避重试；若持续出现，建议查看服务状态页确认是否为大规模故障（仓库内 live-sources.md 的 Errors 条目列出了获取权威错误文档的指引）。不要在同一秒内疯狂重试——退避是标配。

529 Overloaded：服务过载

常见成因：

• API 请求量处于高峰
• 服务容量已达上限

修复思路：指数退避重试；同时可考虑：

• 换用负载通常更低的模型（Haiku 往往比 Opus/Sonnet 更不容易被打满）
• 将请求分散到不同时间点
• 在客户端实现请求排队（request queuing）

六、常见错误速查表

最后一行值得展开：大多数情况下你根本不需要手写重试——SDK 已内置 429/5xx 的指数退避自动重试，通过max_retries（默认 2）即可配置。只有当默认行为不够用时（如需要自定义退避上限、需要把retry-after响应头纳入退避计算）才考虑自定义重试。

七、SDK Typed Exceptions：用类型而不是字符串判断错误

始终使用 SDK 提供的 typed exception 类，绝不要用字符串匹配错误信息来区分错误类型。每个 HTTP 错误码都映射到特定的异常类：

正确写法（TypeScript）：

// ✅ Correct: use typed exceptions try { const response = await client.messages.create({...}); } catch (error) { if (error instanceof Anthropic.RateLimitError) { // Handle rate limiting } else if (error instanceof Anthropic.APIError) { console.error(`API error ${error.status}:`, error.message); } }

错误写法（禁止）：

// ❌ Wrong: don't check error messages with string matching try { const response = await client.messages.create({...}); } catch (error) { const msg = error instanceof Error ? error.message : String(error); if (msg.includes("429") || msg.includes("rate_limit")) { ... } }

关键要点

• 所有异常类都继承自Anthropic.APIError，基类携带status属性
• 使用instanceof判断时从最具体到最不具体排列（例如先检查RateLimitError，再检查APIError），避免具体异常被基类提前截获
• 仓库内 python/claude-api/README.md 的 "Error Handling" 一节给出了 Python 侧完整的异常分支示例：按BadRequestError→AuthenticationError→PermissionDeniedError→NotFoundError→RateLimitError→APIStatusError（区分 5xx 与 4xx）→APIConnectionError（网络层错误）的顺序逐级捕获，并单独处理RateLimitError的retry-after头——这套分支结构可直接作为生产代码的模板。

八、进阶：自定义指数退避重试的参考实现

尽管 SDK 默认自动重试，但当你需要超出默认行为（例如更深的重试次数、可配置的退避上限）时，仓库内的 Python 示例给出了完整实现模式，要点是：只对 429 与 5xx 重试，其余 4xx 立即抛出：

import time import random import anthropic def call_with_retry( client: anthropic.Anthropic, max_retries: int = 5, base_delay: float = 1.0, max_delay: float = 60.0, **kwargs ): """Call the API with exponential backoff retry.""" last_exception = None for attempt in range(max_retries): try: return client.messages.create(**kwargs) except anthropic.RateLimitError as e: last_exception = e except anthropic.APIStatusError as e: if e.status_code >= 500: last_exception = e else: raise # Client errors (4xx except 429) should not be retried delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay) print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s") time.sleep(delay) raise last_exception

实现亮点：指数退避base_delay * 2^attempt之外叠加随机抖动（jitter）避免"惊群"同步重试，并用max_delay封顶。这与错误码总览中的 Retryable 列完全对应——只有标 Yes 的错误码（429/500/529）才进入重试循环。

九、实战排查流程与技能内配套资源

把以上内容串成一条可落地的排查链路：

1. 看状态码与 Retryable 列：429/5xx → 进重试逻辑；其余 4xx → 直接修请求；
2. 读错误响应体：error.type与error.message精确定位问题，request_id留存用于反馈；
3. 按成因对照修复：角色交替、模型 ID、key 权限、请求体大小、参数移除（Opus 4.7）——全部集中在文中的两张速查表；
4. 代码层：优先依赖 SDK typed exception 与内置重试，仅按需自定义（参考第八节实现）。

本技能在仓库内的配套资料可继续深入：

• error-codes.md：本文档源文件（HTTP 错误码总参考）
• model-migration.md：模型迁移指南，含 Opus 4.7 全部会触发 400 的破坏性变更、旧模型退役替换表与逐 SDK 语法对照
• python/claude-api/README.md：Python SDK 安装、快速开始、错误处理与自定义重试示例
• typescript/claude-api/README.md：TypeScript SDK 对应内容
• live-sources.md：官方权威文档的获取指引（含 Errors 主题），当缓存内容可能过期时按其中的说明获取最新信息
• models.md：精确模型 ID 与能力清单，排查 404 时的权威依据

十、注意事项与边界

• 本文描述的错误码、SDK 类名与默认值（如max_retries=2）均以当前仓库内置技能文档为准；模型能力与参数约束随版本演进可能变化，涉及最新能力时以 live-sources.md 指向的官方实时文档为准。
• 不要把 API key 硬编码进代码或提交进仓库；统一走ANTHROPIC_API_KEY环境变量。
• 迁移类改动（如从 Opus 4.6 升到 4.7）在动手前先确认改动范围，且每个改动都应向使用者说明原因——这是技能文档反复强调的协作纪律，也是避免 400/404 批量爆发的第一道防线。

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体