claude code 错误码说明

一、4xx 客户端错误（必须自己改代码 / 配置）

400 invalid_request_error

含义：请求格式 / 参数错误Claude
常见：JSON 不合法、参数名写错、model 名写错、prompt 超长
处理：检查请求体、参数名、模型名，不要直接重试

401 authentication_error

含义：认证失败，API Key 无效 / 缺失Claude
常见：没带 Key、Key 写错、过期、被撤销、前缀不是 sk-ant-api03-
处理：核对 Key、重新生成、检查环境变量

402 billing_error

含义：计费 / 支付问题Claude
常见：余额不足、信用卡过期、欠费冻结
处理：控制台充值、更新支付方式Claude

403 permission_error

含义：权限不足Claude
常见：Key 无权访问该模型 / 接口、地域限制、组织被禁用
处理：检查角色权限、换可用地域Claude

404 not_found_error

含义：资源不存在Claude
常见：model 名错误、endpoint 路径错、资源 ID 不存在
处理：核对模型名（如 claude-3-5-sonnet-20260620）、接口地址

413 request_too_large

含义：请求体过大Claude
限制：标准接口最大 32MB，prompt + 上下文超长
处理：缩短 prompt、分批上传、减少上下文Claude

422 unprocessable_entity

含义：内容违规 / 策略不通过
常见：敏感内容、违禁话题、安全策略拦截
处理：修改 prompt，去掉敏感内容，不要重试

429 rate_limit_error

含义：速率限制超限Claude
类型：
RPM：每分钟请求数超限
TPM：每分钟 token 超限
并发请求数超限
响应：通常带 Retry-After: X 秒
处理：必须退避重试（指数退避）、限流、降频

二、5xx 服务端错误（可重试）

500 api_error

含义：服务器内部未知错误Claude
处理：短暂退避后重试，多次失败再联系官方

529 overloaded_error（常见也会返回 503）

含义：服务器过载 / 繁忙 / 维护
处理：较长间隔重试（10–30 秒），错峰请求

503 网关超时

含义：服务器网关超时，后台会重试。
处理：短暂退避后重试，多次失败再联系官方

claude code 错误码说明

一、4xx 客户端错误（必须自己改代码 / 配置）#

400 invalid_request_error#

401 authentication_error#

402 billing_error#

403 permission_error#

404 not_found_error#

413 request_too_large#

422 unprocessable_entity#

429 rate_limit_error#

二、5xx 服务端错误（可重试）#

500 api_error#

529 overloaded_error（常见也会返回 503）#

503 网关超时#