4、客户端错误码解析（4xx系列）
4xx系列错误码，说白了就是「你这边有问题」。服务器端收到了你的请求，但没法处理，因为请求本身就不对。我刚入行那会儿，看到这些错误码总觉得是后端在甩锅，后来自己调试多了才明白，确实是客户端自己挖的坑。
4.1 4xx 状态码的分类与区别
开始单聊具体错误码之前，我个人习惯先把这些码子分清楚。很多人容易搞混，特别是401和403，网上资料也写得模棱两可。你看这张对比表就清楚了：
| 错误码 | 含义 | 典型场景 | 排查方向 |
|---|---|---|---|
| 400 | Bad Request | 请求参数错误 | 检查请求体格式 |
| 401 | Unauthorized | 未提供有效身份凭证 | 检查/ |
| 403 | Forbidden | 有凭证但没权限 | 检查权限配置 |
| 404 | Not Found | 路径/资源不存在 | 检查URL拼接 |
| 405 | Method Not Allowed | 接口不支持该HTTP方法 | 检查HTTP动词 |
我的小提示：调试时先看状态码，再读响应体的 message 字段。很多 SDK 把错误细节写在 body 里，只看状态码容易漏掉关键信息。我曾经有个同事盯着 400 看了半天，结果 body 里明确写着 "field 'email' should be a string"。
4.2 400 Bad Request —— 请求格式不对
400大概是我们在SDK集成中碰到的头号敌人。它意思就是：你发的东西服务器看不懂或者不满足要求。
常见的坑有：
- JSON 格式错误：多了一个逗号，或者字符串没加引号。我就遇到过好几次，复制粘贴时把注释带进去了——JSON 不允许注释。
- 缺少必填字段：接口文档写了必须传
user_id，你漏掉了。很多 SDK 会有参数校验，但校验不一定全面。 - 参数类型不匹配：文档要求
age是整数，你传了个字符串"18"。有些服务端会强校验类型。
// 错误示例：JSON 格式不对
POST /api/users
Content-Type: application/json
{
"name": "张三",
"age": "25" // 类型不对，服务端可能期望的是数字
}排查思路：先打印出你发送的完整请求体，用在线 JSON 校验工具跑一遍。如果没问题，再对着接口文档一个一个字段核对。嗯，这里有个细节容易被忽略——注意区分 null 和空字符串，很多接口对这两个的处理完全不一样。
4.3 401 vs 403 —— 没认证 vs 没授权
这两个经常被搞混。我简单给出区分：
- 401 Unauthorized：你没登录，或者登录凭证过期了。服务器不知道你是谁。
- 403 Forbidden：服务器知道你是谁，但你没权限干这件事。
举个例子：
- 你用游客身份访问用户列表 → 401，因为你没登录。
- 你登录了普通账号，但试图删除管理员才能删的内容 → 403，因为权限不够。
重点区分：401 是「你是谁？」的问题，403 是「你凭啥？」的问题。
我在项目中遇到过几次 SDK 用户报 401，结果查下来是 过期了，但 SDK 没有做自动刷新。个人建议：集成 SDK 时一定要处理好 的生命周期，过期前预刷新或者捕获到 401 后主动刷新。
// 过期后的处理逻辑（伪代码）
if (response.status === 401) {
await refreshToken();
// 重试原始请求
return originalRequest();
}4.4 404 Not Found —— 资源找不到
404 不只是打开网页时才出现。SDK 集成里遇到 404，多半是：
- API 路径写错了：大小写敏感，多了一个斜杠或少了一个路径段。我曾经花了一小时发现路径末尾多了一个
/，不同框架对路径末尾斜杠的处理方式不一样。 - 资源不存在：请求的 ID 已经被删除了，或者你拼错了 ID。
- 版本号不对：
/v1/books走成/v2/books，而 v2 根本没这个接口。
避坑：我曾经用 Postman 测试没问题，换到 SDK 就 404。最后发现是 SDK 自动在 base URL 后面拼接了路径，导致路径重复了。所以一定要打出来看看最终请求的完整 URL 是什么。
4.5 405 Method Not Allowed —— 方法用错
接口明明只接受 POST，你发了 GET。或者反过来。这年头 RESTful 接口逐渐少了，但很多老 SDK 还在用。我建议你在调试时先确认接口文档里定义的 HTTP 方法：
- GET：获取资源，只读
- POST：创建资源
- PUT：全量更新资源
- PATCH：部分更新资源
- DELETE：删除资源
如果你用了 curl 或者某些 HTTP 客户端，默认可能是 GET，但是你忘了改成 POST。这种低级错误其实挺常见的。我记得有一次收到用户工单说 SDK 报 405，查了半天发现是代理服务器改了请求方法——这类问题排查起来最头疼。
4.6 其他容易碰到的 4xx 错误码
除了上面五个常见的，还有些 4xx 偶尔会遇到：
| 错误码 | 含义 | 简要说明 |
|---|---|---|
| 408 | Request Timeout | 请求超时，可能是网络慢或服务器忙 |
| 409 | Conflict | 资源冲突，比如创建重复用户 |
| 413 | Payload Too Large | 上传文件/数据体过大 |
| 429 | Too Many Requests | 触发限流，请求太频繁 |
| 451 | Unavailable For Legal Reasons | 内容被屏蔽（法律原因） |
说真的，429 我碰到的最多。限流在很多业务场景下是个常态，SDK 里如果没做重试逻辑，用户就会一直报错。我建议 SDK 层面加上指数退避（Exponential Backoff）的重试，对 429 和 5xx 都有效果。具体的重试策略后面章节会详细说，这里先提一嘴。
核心方法论：我个人调试 4xx 问题的固定步骤：
- 看状态码，确认是哪一大类
- 读取响应体的
message或error字段 - 用日志打印出完整请求（URL、Header、Body）
- 对照接口文档，逐项核对
- 用 Postman 或 cURL 做对比测试，排除 SDK 本身问题
好了，4xx 系列的核心错误码就这些。你想想看，其实基本都是格式、权限、路径、方法这四个维度的问题。搞清楚了这些，日常 SDK 集成遇到的 90% 的客户端错误都能快速定位。下次再看到 4xx，不用慌，按这个思路排查就行。