浏览 AI 知识库
API 返回 401、403、404、429、500，先查客户端还是上游
401、403、404、429 和 500 指向的故障层不同。保留原请求和响应，一次只检查认证、权限、路径、限流或服务端中的一层，比不断换 Key 更快。
看到 API 报错先别重写代码，先判断是谁拒绝了请求
接口返回 403，开发者连续更换 API Key、重写请求并重启服务。最后发现 Token 有效，但当前账号没有目标项目权限。
- 完整状态、响应和 requestId 已保留
- 一次只验证一个层级
- 修复后用原请求复测
API 错误码排查，先从“401 / 403”这一类现象查起
401 / 403
- 原因
- 认证缺失或失效，或身份有效但无资源、动作或网络权限。
- 怎么改
- 核对令牌类型、过期、scope、用户/组织/资源和服务端授权日志；区分未认证与已认证无权。
404
- 原因
- 路径、版本、资源 ID、反向代理或权限隐藏可能导致未找到。
- 怎么改
- 从最小端点逐段核对 host、base path、路由和资源存在性，检查上游实际收到的路径。
429
- 原因
- 请求、并发、令牌、账号配额或上游池限流。
- 怎么改
- 读取响应头和文档，记录时间窗与请求 ID，按规则退避；不要无上限并发重试。
500 / 502 / 503 / 504
- 原因
- 应用异常、代理上游、依赖不可用或超时边界。
- 怎么改
- 关联同一请求在代理、应用和上游的时间线，找第一处失败和完整错误，不以最后状态码代替根因。
复测前，固定原始现象、环境和目标
| 需要确认 | 本例内容 |
|---|---|
| 现有材料 | 请求时间 14:32、requestId `a91c`、状态 403、响应含 `insufficient_scope`；同 Token 可访问 `/me`。 |
| 不能越过的边界 | 按客户端、认证、授权、资源、限流、服务端分层；保留完整响应和时间线；不在日志中暴露 Token。 |
| 要交付的结果 | 分层诊断记录 |
浏览器只看到 502，第一处失败其实是应用访问上游超时
| 时间 | 层级 | 证据 | 能得出的结论 |
|---|---|---|---|
| 10:42:18.091 | 客户端 | POST /api/report，x-request-id=req-6a21 | 请求已到本站，保留同一关联 ID |
| 10:42:18.106 | 反向代理 | 转发 app:3000，连接成功 | 不是代理找不到应用 |
| 10:42:18.121 | 应用 | 调用 reports-upstream.example.test | 进入外部依赖阶段 |
| 10:42:23.123 | 应用 | upstream timeout after 5000 ms | 第一处明确失败 |
| 10:42:23.125 | 反向代理 | 502，upstream_response_time=5.004 | 502 是结果，不是根因 |
域名、时间和请求 ID为教学构造。真实排查必须统一时区，并从客户端、代理、应用和上游保留同一请求的原始记录。
API 错误码排查：按原条件复测的结果
原始现象
只看到“请求失败”，每次同时改 Key、URL 和代码，无法知道哪个条件起作用。
分层诊断记录
诊断确认认证成功、资源存在，失败位于授权 scope；申请只读项目 scope 后同一请求返回 200。记录同时说明 401、404、429、500 的不同证据入口，没有把所有错误归因于 Key。