API集成前为什么要先读错误码
API 集成前先读错误码，是为了提前知道哪些错误能重试、哪些要让用户修改、哪些要联系服务方、哪些必须记录 request id 和响应头，避免把联调问题带到线上。
很多 API 集成一开始都很顺利：拿到 token，复制示例请求，返回 200，页面显示成功。麻烦往往出现在第二天：某个用户没权限，某个字段格式不对，某个接口限流，某次网络超时后重复创建了对象，某个 404 不是资源不存在而是账号没有访问权，某个 422 需要读响应体才能知道哪个字段错了。此时再回头读错误码文档，往往已经变成线上排障。
API 错误码不是文档角落里的附录，而是集成设计的一部分。它告诉你请求失败时该做什么：重试、提示用户、刷新授权、等待限流窗口、联系服务方、记录证据、停止自动任务，还是进入人工处理。读错误码越早，联调越像工程设计；读得越晚，错误处理越像临时补丁。
MDN 的 HTTP status 文档说明，响应状态码用于表示一次 HTTP 请求是否成功，并按首位数字分成五类：1xx 信息响应、2xx 成功、3xx 重定向、4xx 客户端错误、5xx 服务端错误。RFC 9110 也说明，状态码是三位整数，有效范围是 100 到 599，首位数字定义响应类别。这个分类很有用，但它只是一层。真实 API 通常还会在响应体里提供业务 error code、message、request id、字段级错误、限流信息和文档链接。
如果只看“是不是 200”，集成会很脆弱。如果只看 HTTP 大类，不看业务错误码，也会误判。400、401、403、404、409、422、429、500、502、503 看起来都是失败，但处理方式完全不同。API 集成前先读错误码，就是提前把这些分支画出来。
<figure><img src="/media/api-error-codes-before-integration-20260703-error_code_map.png" alt="API错误码地图"><figcaption>API 错误处理要同时看 HTTP 状态码、业务 error code、响应头、request id 和字段级错误。</figcaption></figure>
先区分三层错误
第一层是传输层错误。它可能没有标准响应体，例如 DNS 失败、TLS 失败、连接超时、读超时、代理断开。Stripe 的 advanced error handling 文档把 network errors 描述为客户端和服务端之间连接问题，可能表现为 socket 或 timeout 异常。这类错误最难判断，因为客户端可能不知道服务端是否收到了请求。此时是否能重试，取决于接口是否幂等、是否有幂等键、是否能查询最终状态。
第二层是 HTTP 状态码。4xx 通常表示请求侧需要修改，5xx 通常表示服务端处理失败或暂时不可用，429 表示限流，401/403 与认证和权限有关，404 可能是资源不存在，也可能是访问范围不足。MDN 和 IANA 的状态码资料能帮助你理解通用语义，但每个平台仍可能给出自己的细节说明。
第三层是业务错误码。Stripe 错误码文档说明，部分 API errors 会包含 code 属性，帮助开发者判断下一步；Stripe 错误处理文档也提醒，这类错误可能在集成工作正常时出现，开发者应根据 error code 决定后续动作。比如卡片拒付、参数无效、幂等键冲突、资源状态不允许操作，都不是简单重试能解决的问题。
联调时要把这三层都记录下来：HTTP 状态码、响应头、业务 error code、message、request id、请求参数摘要和本地 trace id。这样排查问题时，才不会只有一句“接口失败了”。
错误码决定用户提示
错误处理不只是日志问题，也会影响用户体验。一个 400 参数错误，应该告诉用户哪个字段需要修改；一个 401，可能需要重新授权；一个 403，应该提示当前账号没有权限；一个 404，可能要区分“资源不存在”和“你看不到”；一个 409，可能表示状态冲突或重复操作；一个 422，常用于验证失败或语义不符合要求；一个 429，应提示稍后再试或排队；一个 5xx，则不应把服务方内部细节原样展示给用户。
GitHub REST API 文档建议查看响应状态码和响应头，响应头中可能包含额外信息；Getting started 文档也举例说明 x-ratelimit-remaining 和 x-ratelimit-reset 可以告诉你某个时间窗口内还剩多少请求。对接这类 API 时，如果前端只显示“请求失败”，用户不知道是自己操作错、权限不够，还是平台暂时忙。
更好的做法是把错误分层映射成用户语言。开发日志保留细节，用户提示保持简洁，客服或运营后台显示可追踪线索。例如：字段错误提示用户修正；权限错误提示更换账号或联系管理员；限流提示等待；服务端错误提示稍后重试并记录 request id。这样既减少困惑，也减少客服排障成本。
重试不是看到失败就再发一次
很多线上事故来自错误重试。网络超时后重复创建订单，5xx 后重复扣费，429 后无间隔重试，批量任务失败后从头再跑导致重复写入。这些都说明集成前没有读清楚重试边界。
Stripe 的 advanced error handling 文档把 idempotency and retries 作为单独主题，说明幂等性让某些请求在没有响应时可以更安全地重复执行。Stripe error handling 文档也建议在连接错误发生时，可使用相同 idempotency key 重复请求，直到收到明确成功或失败。这个原则可以推广理解：会产生副作用的 POST/写入请求，不能和普通 GET 查询一样随意重试；如果服务提供幂等键，要在创建、扣费、提交等动作中使用；如果没有幂等机制，就应先查状态、再决定是否补发。
重试还要看错误类型。400、401、403、422 通常需要修改请求、授权或数据，不适合盲目重试。429 应读取限流说明和可能存在的 Retry-After 或重置时间。502、503、504 可能适合退避重试，但仍要设置次数上限、间隔和熔断。网络超时要结合幂等键或查询接口判断最终状态。
<figure><img src="/media/api-error-codes-before-integration-20260703-retry_strategy_map.png" alt="API重试策略图"><figcaption>重试策略要根据错误类型、幂等性、限流头和副作用风险决定，不是失败就立刻再发。</figcaption></figure>
响应头经常比错误文案更有用
API 文档里的错误章节常常会提到响应头。GitHub 文档说明，可以用包含响应头的请求方式查看状态码和 headers，并提到 x-ratelimit-remaining、x-ratelimit-reset 这类限流信息。RFC 9110 对 Retry-After 的语义也有说明：服务端可用它表示用户代理在多久之后再发请求。
联调时，不要只打印响应体。至少要记录：status、request id 或 trace id、rate limit 剩余额度、重置时间、retry-after、内容类型、接口版本、错误码和字段级错误。如果服务方让你联系支持团队，通常也会先要 request id、时间窗口和请求摘要。没有这些证据，排查会变成互相猜。
响应头还会影响缓存和条件请求。比如 304 Not Modified 不是失败，表示缓存内容仍可用；ETag、If-None-Match 等机制会改变你对“没有返回完整数据”的理解。对接 API 前读错误码和响应头，能避免把正常协议行为误判成异常。
错误码表要变成本地处理表
读错误码不是看完就算。更实用的方式，是把官方错误码整理成本地处理表。表里至少有六列：状态码、业务 code、含义、是否可重试、用户提示、记录字段。对于重要接口，再加上是否需要人工处理、是否需要告警、是否可能重复执行、是否影响资金或权限。
例如，一个用户资料更新接口可能这样处理：400 字段缺失，提示用户修正；401 token 过期，刷新授权或重新登录；403 权限不足，提示管理员授权；409 版本冲突，重新拉取数据再让用户确认；422 字段语义错误，展示字段级提示；429 限流，排队并延迟；5xx，退避重试并记录 request id；网络超时，先查操作结果再决定是否补发。
这个表应和代码一起维护。接口升级、错误码新增、套餐权限变化、限流规则调整，都要更新处理表和测试用例。很多团队只写成功路径测试，结果上线后第一批异常就暴露问题。错误码表可以直接转成单元测试、联调脚本和告警规则。
<figure><img src="/media/api-error-codes-before-integration-20260703-api_call_flow.png" alt="API调用流程图"><figcaption>API 调用链路要从请求前校验、发送、解析、分类处理、记录证据到人工处理连成流程。</figcaption></figure>
联调前的检查清单
第一，确认认证错误。token 缺失、token 过期、scope 不足、账号无权限，要有不同处理。第二，确认参数错误。字段缺失、类型不对、枚举值不合法、长度超限、时间格式错误，要能映射到用户可理解的提示。第三，确认资源错误。资源不存在、资源已删除、资源状态不允许操作、资源被另一个流程占用，都要区分。
第四，确认限流和配额。读取限流文档、响应头、重置时间和套餐差异。第五，确认幂等和重复提交。创建类接口是否支持 idempotency key，是否能用外部订单号、业务 ID 或去重键查询最终状态。第六，确认服务端错误。哪些 5xx 可重试，多久重试，最多几次，失败后是否告警。第七，确认网络错误。超时后先查状态还是补发，是否可能造成重复副作用。
第八，确认日志证据。每次失败至少要记录本地 trace id、请求时间、接口名、状态码、业务 code、request id、限流头、重试次数和用户可见提示。第九，确认人工路径。自动处理不了时，谁看、在哪里看、需要什么信息、如何重新执行。第十，确认测试样本。准备一组故意失败的数据，覆盖认证、权限、字段、限流、重复提交和服务端错误模拟。
<figure><img src="/media/api-error-codes-before-integration-20260703-integration_checklist.png" alt="API联调清单"><figcaption>联调前把认证、字段、权限、限流、幂等、重试、日志和人工处理写成清单，能减少线上临时修补。</figcaption></figure>
错误码也要进入上线检查
很多团队把错误处理留给代码评审时顺手看一眼，这还不够。API 集成上线前，应把错误码处理列入检查：是否能识别认证失败，是否能识别权限不足，是否能从字段错误中拿到具体字段，是否能读取限流头，是否能记录 request id，是否能区分网络超时和服务端失败，是否能避免重复提交，是否有人工处理入口。
检查方式可以很简单：准备一组模拟错误样本。用错误 token 测 401，用权限不足账号测 403，用缺字段请求测 400 或 422，用不存在资源测 404，用重复业务 ID 测冲突，用高频请求观察 429，用临时断网或超时模拟网络错误。每个样本都要检查三件事：用户看到什么，日志记录什么，系统下一步做什么。
上线后也要观察错误分布。某个版本上线后 422 突然增多，可能是字段映射变了；401 增多，可能是授权刷新失败；429 增多，可能是批量任务频率过高；5xx 增多，可能是服务方异常，也可能是请求形态触发了问题。错误码不是只在失败时看，它也是长期监控的信号。
结语：先读错误码，是为了设计失败路径
API 集成不是把成功示例跑通就完成。成功路径只说明你会调用接口，错误路径才说明系统能不能上线。错误码文档能告诉你哪些问题来自请求，哪些来自权限，哪些来自服务端，哪些需要等待，哪些需要用户修改，哪些需要记录 request id，哪些不能随意重试。
提前读错误码，能让你在代码里建立清晰分支：用户可修正的提示给用户，开发要看的证据进日志，平台暂时问题进入重试，副作用动作使用幂等，未知错误进入人工处理。这样做不会让接口永远不出错，但会让错误来临时有路可走。
对开发者和运营系统来说，错误码不是失败后的说明书，而是集成前的设计材料。先读它，再写调用代码，联调会少很多猜测，线上也会少很多无法解释的“请求失败”。