HTTP 状态码与网关排查速查
常用命令
curl -sS -o /dev/null -w '%{http_code}\n' https://example.com
curl -sS -I https://example.com
curl -sS -D - -o /dev/null https://example.com
curl -sS -o /dev/null -w '%{http_code} %{time_total}\n' https://example.com
curl -sS -L -o /dev/null -w '%{http_code} %{url_effective}\n' http://example.com
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health
curl -sS -H 'Host: api.example.com' http://10.0.0.10/health
curl -sS --resolve api.example.com:443:10.0.0.10 https://api.example.com/
curl -sS -k -o /dev/null -w '%{http_code}\n' https://example.com
curl -sS -X POST -H 'Content-Type: application/json' -d '{}' -w '%{http_code}\n' https://api.example.com/v1
场景速查
| 目的 |
写法/命令 |
注意 |
| 继续请求 |
100 Continue |
中间响应，不是最终结果 |
| 协议升级 |
101 Switching Protocols |
WebSocket 等升级场景 |
| 请求成功 |
200 OK |
不代表业务逻辑成功 |
| 创建成功 |
201 Created |
常配合 Location |
| 成功无响应体 |
204 No Content |
不能携带 body |
| 永久重定向 |
301 Moved Permanently |
缓存行为需评估 |
| 临时重定向 |
302 Found |
客户端可能改为 GET |
| 缓存命中 |
304 Not Modified |
不能携带响应体 |
| 请求参数错误 |
400 Bad Request |
查客户端请求体与字段 |
| 未认证 |
401 Unauthorized |
缺凭证或 token 失效 |
| 已认证无权限 |
403 Forbidden |
查 ACL、RBAC、IP 限制 |
| 资源不存在 |
404 Not Found |
也可能是路由或代理路径错 |
| 请求被限流 |
429 Too Many Requests |
看 Retry-After 与配额 |
| 客户端断开 |
499 Client Closed Request |
Nginx 自定义，查上游耗时 |
| 上游响应非法 |
502 Bad Gateway |
上游崩溃、端口或协议错 |
| 服务不可用 |
503 Service Unavailable |
无健康后端、维护或限流 |
| 上游超时 |
504 Gateway Timeout |
上游慢或超时配置过短 |
易错点
- 错误：把 401 和 403 都当“没登录”；正确：401 是未认证，403 是已认证但被拒绝。
- 错误：认为 502 一定是后端进程挂了；正确：还可能是端口写错、协议不匹配、TLS 失败或响应非法。
- 错误：把 504 当后端返回的错误；正确：504 通常由网关生成，后端可能仍在处理。
- 错误：看到 499 去查后端状态码；正确：499 表示客户端已断开，重点看上游耗时和客户端超时。
- 错误：认为 429 只来自业务应用；正确：网关、WAF、API Server 都可能限流，需看响应头。
- 错误：用
curl -I 验证所有接口；正确：HEAD 与 GET 行为可能不同，必要时用 -D - -o /dev/null。
- 错误：重定向后只看首个状态码；正确：加
-L 并用 %{url_effective} 确认最终地址。
- 错误：把 503 当永久故障；正确：先看健康检查、后端列表、连接池和限流状态。
- 错误：给 204/304 写响应体；正确：这两个状态不应携带 body。
相关命令
读完自测
- 401 与 403 的区别是什么？
- 499 由谁记录，常见原因是什么？
- 502 与 504 的区别是什么？
答案
- 401 表示未认证，403 表示已认证但没有访问权限。
- 由 Nginx 记录，表示客户端在响应前主动断开，常见于上游处理过慢。
- 502 是网关收到上游非法响应，504 是网关等待上游响应超时。