API 返回 401、403、404、429、500，先查客户端还是上游

状态码是定位入口，不是根因

先保存完整请求链，再判断错误来自客户端参数、身份与权限、路由、限流、应用、代理还是上游。不要看到 401 就只换 Key，看到 500 就只重启。

401 / 403

常见原因：认证缺失或失效，或身份有效但无资源、动作或网络权限。

处理方法：核对令牌类型、过期、scope、用户/组织/资源和服务端授权日志；区分未认证与已认证无权。

把涉及的文件、目录、版本、命令和实际输出写进记录；代码变化同时保留 diff 与测试结果。

404

常见原因：路径、版本、资源 ID、反向代理或权限隐藏可能导致未找到。

处理方法：从最小端点逐段核对 host、base path、路由和资源存在性，检查上游实际收到的路径。

确认“404”已经有可回查结果，再进入“429”；依据仍然来自猜测时，把缺口单列并停在当前步骤。

429

常见原因：请求、并发、令牌、账号配额或上游池限流。

处理方法：读取响应头和文档，记录时间窗与请求 ID，按规则退避；不要无上限并发重试。

确认“429”已经有可回查结果，再进入“500 / 502 / 503 / 504”；依据仍然来自猜测时，把缺口单列并停在当前步骤。

500 / 502 / 503 / 504

常见原因：应用异常、代理上游、依赖不可用或超时边界。

处理方法：关联同一请求在代理、应用和上游的时间线，找第一处失败和完整错误，不以最后状态码代替根因。

需要修改时先限定文件和行为范围，无法说明回滚方式或影响面的动作先不执行。 完成后把证据归入“分层诊断记录”。

诊断记录应排除而不是猜测

保存脱敏请求、环境、时间、状态、响应头体、请求 ID、各层日志、已排除项和复测结果。根因没有证据时明确写假设。