HTTP 状态码完全指南｜常见错误原因和解决方案
开发 API 时收到了 422 响应。在生产环境中突然开始出现 502。重定向是 301 还是 302 会改变 SEO 影响。HTTP 状态码是网络开发的通用语言，正确理解它们是故障排除的第一步。
状态码的 5 个类别
| 范围 | 类别 | 含义 |
|---|---|---|
| 1xx | Informational | 已接收请求并处理中 |
| 2xx | Success | 请求成功 |
| 3xx | Redirection | 需要额外操作（重定向） |
| 4xx | Client Error | 客户端问题 |
| 5xx | Server Error | 服务器端问题 |
开发者最常遇到的代码
200 OK — 成功
最基本的成功响应。API 正在按预期工作。
301 Moved Permanently — 永久重定向
用于 URL 永久更改的情况。从 SEO 角度来说，旧 URL 的权重会转移到新 URL，这对网站迁移和 HTTPS 化至关重要。Google 将 301 视为「信号转移」。
常见问题：本意返回 301 却返回了 302。Apache 的 Redirect 默认为 302。应明确指定 Redirect 301。
302 Found — 临时重定向
临时重定向。用于 A/B 测试和维护期间的迂回。SEO 评价不会转移。
304 Not Modified — 缓存有效
当浏览器使用 If-Modified-Since 或 If-None-Match 标头发送条件请求，且资源未更改时返回。不发送正文，因此可以节省带宽。
400 Bad Request — 请求错误
服务器无法解析请求。原因：无效的 JSON、缺少必需参数或 Content-Type 不匹配。
# よくあるミス: Content-Type を指定していない
curl -X POST https://api.example.com/users -d '{"name":"Alice"}'
# → 400 (Content-Type: application/json が必要)
# 正しい
curl -X POST https://api.example.com/users \
-H 'Content-Type: application/json' \
-d '{"name":"Alice"}'401 Unauthorized — 需要身份验证
缺少或无效的认证凭据。Bearer 令牌已过期，或 API Key 错误。
403 Forbidden — 禁止访问
认证通过，但权限不足。例如普通用户访问管理员专用端点时。与 401 的区别是「认证有无」vs「权限有无」。
404 Not Found — 找不到资源
最著名的错误。由 URL 拼写错误、已删除的页面或路由配置错误引起。出于 SEO 目的，有时使用 410 Gone 来表示「已意图删除」更为合适。
413 Payload Too Large — 大小超出
文件上传中常见。检查 Nginx 的 client_max_body_size（默认 1MB）、PHP 的 upload_max_filesize 和 API Gateway 限制。
422 Unprocessable Entity — 验证错误
JSON 语法正确但在业务逻辑上无效（无效的电子邮件格式、必填字段为空等）。REST API 通常为验证错误返回这个。
429 Too Many Requests — 速率限制
在短时间内发送了过多请求。Retry-After 头指示应等待的秒数。对策：实现指数退避 (exponential backoff)。
500 Internal Server Error — 服务器内部错误
未处理的异常、NULL 引用、配置文件错误。最危险的错误。务必检查服务器日志。
502 Bad Gateway — 上游服务器异常
反向代理 (Nginx) 无法连接到上游的 PHP-FPM / Node.js / Python WSGI 或收到无效响应。检查上游进程重启、内存不足或套接字连接超时。
503 Service Unavailable — 服务临时不可用
维护中或服务器过载。包含 Retry-After 标头来告知客户端等待。
504 Gateway Timeout — 上游超时
上游服务器未及时响应。繁重的 DB 查询、外部 API 延迟。检查 Nginx 的 proxy_read_timeout。
DevLab 状态码搜索工具
HTTP 状态码搜索工具可以通过代码号或关键字（例如「redirect」、「forbidden」、「timeout」）立即搜索，并在一个列表中查看每个代码的含义、原因和解决方案。完全在浏览器中运行，无需注册。
总结
HTTP 状态码是服务器和客户端的通用语言。关键知识包括 301 vs 302 的 SEO 影响、400 vs 422 的验证区分以及 5xx 的基础设施诊断。遇到问题时，首先检查状态码，然后应用上述补救措施。