遇到 401、403、429 或 503 时，如何排查 API 错误

修改之前先收集错误信息

记录请求方法、接口地址、状态码、发生时间和可用的请求编号。读取错误正文与相关响应头，同时判断响应来自哪里：API 应用、网关或防护代理可能因不同原因拒绝请求。

先用一个最小请求复现，不要立即启动大量重试。与成功请求比较，每次只修改一个因素。截图和日志中不要保留 Authorization、Cookie 或包含凭据的完整 URL；提交问题时，请求编号通常更适合分享。

先查原因，再决定是否重试

遇到 401，检查凭据和认证方式；遇到 403，检查权限及目标资源。反复发送相同的被拒请求通常不能解决问题。

分别排查 401 和 403

遇到 401，检查凭据是否存在、是否过期，以及认证方案是否正确，例如 Bearer。符合规范的 401 响应包含 WWW-Authenticate。如果 API 支持刷新流程，刷新一次并重试一次；无限刷新不能修复错误凭据。

遇到 403，检查账号角色、目标资源以及 API 权限。相同用户可能可以读取却不能修改。代理也可能按 IP 或地区阻止访问。重新创建令牌并不会自动获得缺失的权限，应结合错误正文和服务规则判断。

控制重试

对 429 或 503，若提供 Retry-After，应据此等待并限制重试次数。仅重试可安全重复的操作：超时的写入可能已经成功。保留请求 ID，避免记录密钥。

理解 Retry-After 的含义

429 可能针对用户、IP，或多个客户端共享的配额，具体取决于服务。下方示意响应中的 Retry-After: 30 要求等待 30 秒再尝试。该字段也可以是 HTTP 日期，实际客户端需要支持这种格式。

降低并发，让使用同一配额的工作进程共同安排重试。503 还应检查服务状态与网关健康。存在 Retry-After 时遵守它；否则使用有随机扰动的递增等待，并限制总时长。过载时继续大量重试可能延长故障。

HTTP/1.1 429 Too Many Requests
Retry-After: 30

没有收到响应，不等于操作没有执行

创建任务或付款请求可能已经被服务器接受，随后才超时。即使客户端没有收到首次结果，重复提交仍可能生成重复记录。写操作应使用 API 明确支持的幂等机制，或者先查询状态再提交。不要自行添加服务并不支持的幂等请求头。

实用的客户端应区分持续的权限问题与临时故障，限制尝试次数，并记录停止原因。重复 GET 通常比重复 POST 容易处理，但最终要遵守 API 约定。向支持人员提供时间、接口、状态码和请求编号，并移除秘密信息。