HTTP状态码网关缓存调试
状态码不是面试题，它是你和客户端“沟通”的语言。线上误会最多的地方，恰恰是“该返回什么码”。一个 200 包打天下，会让排障与风控越来越难。本文从工程落地角度梳理常见状态码，给出选型标准与排障清单。
首先要把“成功与失败”的边界说清楚：
- 2xx 代表请求被正确接收并处理，返回数据是“业务结果”；
- 4xx 是客户端问题（参数、鉴权、流量策略），要让客户端知道“怎么改”；
- 5xx 是服务端问题，客户端重试可能有效，但也要做好熔断与退避。
几个关键码位：
- 200 OK：一切正常；
- 201 Created：资源已创建，配合Location指向新资源URL；
- 204 No Content：处理成功但无内容，省流量；
- 301/302：重定向，注意区别永久/临时；
- 304 Not Modified：缓存命中，带好Etag/Last-Modified；
- 400 Bad Request：参数错误；
- 401 Unauthorized：未认证或Token过期；
- 403 Forbidden：已认证但无权限；
- 404 Not Found：资源不存在，避免泄漏敏感信息；
- 409 Conflict：资源状态冲突（乐观锁冲突、重复提交）；
- 429 Too Many Requests：限流；
- 500/502/503/504：依赖异常、服务不可用、超时。
工程上更重要的是“上下文约定”：
- 网关、服务、BFF 层统一错误模型；
- 对限流/熔断/黑名单要明确 429/403 的区分；
- 对可重试 vs 不可重试要在响应头或响应体里给出“意图”；
- 前端埋点与后端日志统一采集状态码与 trace-id，快速定位。
缓存相关的返回，建议认真使用 ETag 与 Cache-Control：静态资源优先 Cache-Control: max-age，动态内容结合 ETag 协商缓存，304会让“高频读”成本显著下降。
我们提供的“HTTP状态码大全”工具把完整列表与解释都做了分类整理，联调时可以快速查到“这个码到底应该怎么用”。工作台上常备一份清单，出问题的时候翻一眼，很多“争议”就不会发生。
最后给一份“减少争议”的Checklist：
- 文档里明确每个接口的成功/失败码；
- 非200时，响应体要给出机器可解析的错误码与人类可读的错误信息；
- 限流/熔断要配额外标头提示剩余额度与恢复时间；
- 重定向要指明新地址并注意缓存策略；
- 线上告警按状态码维度聚合。
把状态码用对，团队沟通会顺畅很多，系统的可观测性也会整体提升。
相关在线工具：
- 立即查询 HTTP 状态码