HTTP状态码：SDK接入的第一道关卡
做SDK接入，你早晚得跟HTTP状态码打交道。说白了，每次客户端跟服务器握手，服务器都会回复一个三位数的状态码。这数字看似简单，却是判断问题根因最直接的线索。我见过不少开发者，一看到4xx或5xx就慌了，其实只要掌握了规律，排查效率能翻倍。
2xx 成功类：别以为返回200就万事大吉
200 OK 是大家最喜欢的码。但我在项目中遇到过好几次，200里包裹的错误码才是真正的问题。服务器网关正常，业务层却挂了。
检查响应体里的 bizCode 或 success 字段。有些SDK在HTTP层返回200，业务层却抛出异常，这得看文档里的业务码表。
其他2xx比较少见，比如201 Created多用于资源创建场景，204 No Content在删除操作时出现。你对接的SDK如果返回了201或204，一般不需要特殊处理，按文档走就行。
4xx 客户端错误：多半是请求姿势不对
这组码最常见。服务器明确告诉你：你发的包有问题。先怀疑自己，别一上来就甩锅给服务器。
400 Bad Request
请求体格式不对，或者缺少必填参数。比如你传的JSON少了个逗号，或者日期格式不是SDK要求的"yyyy-MM-dd"。我记得有一次查了整整半天，最后发现是Content-Type写成了text/html，服务器根本不认。
- 排查清单
- 检查请求体是否严格符合文档示例
- 确认Content-Type：application/json 还是 application/x-www-form-urlencoded
- 用curl或Postman重放请求，比对差异
401 Unauthorized
没带凭证，或者凭证过期了。OAuth2的过期，失效，都报这个。
401是说「你没登录」或「登录票据无效」。403是说「你登录了，但权限不够」。我曾经在对接一个支付SDK时，因为把API Secret放在了公共参数里而不是签名段，一直报401，后来发现是签名算法少拼了一个冒号。
403 Forbidden
服务器知道你谁，但不让你碰这个资源。常见原因：IP不在白名单、接口没给当前应用开通、套餐过期。
404 Not Found
路径写错了，或者接口版本号不对。很多SDK会升级API版本，旧路径迟早会下掉。我习惯在每个版本的配置文件里写死baseURL和path，升级时统一改。
| 状态码 | SDK中常见表现 | 排查方向 |
|---|---|---|
| 400 | 请求返回空body或错误JSON | 参数格式、Header类型 |
| 401 | 登录态失效，业务无法继续 | 换取、缓存刷新、时间戳同步 |
| 403 | 请求被网关直接拒绝 | IP白名单、接口权限、套餐状态 |
| 404 | 请求无响应，页面/接口不存在 | URL路径、API版本、项目配置 |
5xx 服务器错误：不是你的锅，但需要你来处理
5xx代表服务器自己出了状况。但你作为SDK接入方，不能甩锅就完事，得考虑降级和重试策略。
500 Internal Server Error
服务器内部异常了。可能是数据库连不上，也可能是代码空指针。对接SDK时，500通常是服务器端的问题。我一般会日志里打出完整的requestId，发给SDK提供商时能省很多扯皮时间。
502 Bad Gateway / 503 Service Unavailable
502：网关拿不到上游的响应。503：服务正在维护或过载。这两种情况一般是有计划的重启或突发流量。SDK里必须实现重试机制，但不建议立刻重试。
第一次失败等待 1 秒，第二次 3 秒，第三次 10 秒。最多重试 3 次。超过就报给上层业务做人工介入。别搞死循环重试，服务器恢复期间你重试一万次也没用。
504 Gateway Timeout
请求在超时阈值内没返回。常见于SDK与后端交互时间过长。这时候看超时设置是否合理，以及后端是否能优化响应速度。
一张表帮你速查
| 编码 | 含义 | SDK接入对应动作 | 优先级 |
|---|---|---|---|
| 200 | 成功 | 正常解析响应体 | 无 |
| 400 | 请求参数错误 | 逐一比对文档，修复参数格式 | 高 |
| 401 | 未授权 | 检查/密钥是否最新，刷新凭证 | 高 |
| 403 | 禁止访问 | 检查白名单/套餐/角色配置 | 中 |
| 404 | 接口不存在 | 检查路径、版本、环境配置 | 中 |
| 500 | 服务器内部错误 | 携带requestId向服务商反馈 | 低（由服务商处理） |
| 502/503 | 服务暂不可用 | 指数退避重试，最多3次 | 中 |
| 504 | 网关超时 | 调整超时配置，或优化业务逻辑 | 中 |
我在项目里会写一个中间层，把HTTP状态码映射成统一的SDKError枚举。这样上层业务只知道「网络错误」「鉴权失败」「服务器异常」等业务概念，不需要每个调用方都写一堆if-else。
做SDK接入这些年，我最大的体会是：HTTP状态码不是玄学，它是服务器用最简单的方式告诉你「哪一步错了」。你只要按照4xx查请求、5xx查服务、2xx查响应体这个思路去排查，大部分问题都能在半小时内定位。反过来想，如果什么都不看，逮着码就乱猜，那才真叫浪费时间。