HTTP 状态码完全指南｜常见错误原因和解决方案

开发 API 时收到了 422 响应。在生产环境中突然开始出现 502。重定向是 301 还是 302 会改变 SEO 影响。HTTP 状态码是网络开发的通用语言，正确理解它们是故障排除的第一步。

状态码的 5 个类别

开发者最常遇到的代码

200 OK — 成功

最基本的成功响应。API 正在按预期工作。

301 Moved Permanently — 永久重定向

用于 URL 永久更改的情况。<strong>从 SEO 角度来说，旧 URL 的权重会转移到新 URL</strong>，这对网站迁移和 HTTPS 化至关重要。Google 将 301 视为「信号转移」。

<strong>常见问题</strong>：本意返回 301 却返回了 302。Apache 的 <code>Redirect</code> 默认为 302。应明确指定 <code>Redirect 301</code>。

302 Found — 临时重定向

临时重定向。用于 A/B 测试和维护期间的迂回。SEO 评价不会转移。

304 Not Modified — 缓存有效

当浏览器使用 <code>If-Modified-Since</code> 或 <code>If-None-Match</code> 标头发送条件请求，且资源未更改时返回。<strong>不发送正文</strong>，因此可以节省带宽。

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 目的，有时使用 <code>410 Gone</code> 来表示「已意图删除」更为合适。

413 Payload Too Large — 大小超出

文件上传中常见。检查 Nginx 的 <code>client_max_body_size</code>（默认 1MB）、PHP 的 <code>upload_max_filesize</code> 和 API Gateway 限制。

422 Unprocessable Entity — 验证错误

JSON 语法正确但在业务逻辑上无效（无效的电子邮件格式、必填字段为空等）。REST API 通常为验证错误返回这个。

429 Too Many Requests — 速率限制

在短时间内发送了过多请求。<code>Retry-After</code> 头指示应等待的秒数。对策：实现指数退避 (exponential backoff)。

500 Internal Server Error — 服务器内部错误

未处理的异常、NULL 引用、配置文件错误。<strong>最危险的错误</strong>。务必检查服务器日志。

502 Bad Gateway — 上游服务器异常

反向代理 (Nginx) 无法连接到上游的 PHP-FPM / Node.js / Python WSGI 或收到无效响应。检查上游进程重启、内存不足或套接字连接超时。

503 Service Unavailable — 服务临时不可用

维护中或服务器过载。包含 <code>Retry-After</code> 标头来告知客户端等待。

504 Gateway Timeout — 上游超时

上游服务器未及时响应。繁重的 DB 查询、外部 API 延迟。检查 Nginx 的 <code>proxy_read_timeout</code>。

DevLab 状态码搜索工具

<a href="/ja/tools/http-status/">HTTP 状态码搜索工具</a>可以通过代码号或关键字（例如「redirect」、「forbidden」、「timeout」）立即搜索，并在一个列表中查看每个代码的含义、原因和解决方案。完全在浏览器中运行，无需注册。

相关工具：<a href="/ja/check/headers/">HTTP头验证</a>、<a href="/ja/check/redirect-chain/">重定向链跟踪</a>、<a href="/ja/check/security/">安全诊断</a>。

总结

HTTP 状态码是服务器和客户端的通用语言。关键知识包括 301 vs 302 的 SEO 影响、400 vs 422 的验证区分以及 5xx 的基础设施诊断。遇到问题时，首先检查状态码，然后应用上述补救措施。