HTTP 错误状态码， 4xx 和 5xx 问题排查手册

一、HTTP 4xx 状态码（客户端错误）

4xx 状态码表示客户端请求有误，导致服务器无法正常处理请求。以下是常见 4xx 状态码的详细分析：

1. 400 Bad Request

• 含义：请求语法错误或参数不合法。
• 常见原因：
  • 请求头或请求体格式错误（如 JSON 格式不正确）。
  • 缺少必要的参数或参数值无效。
  • URL 编码错误或请求体过大。
• 排查方法：
  • 检查请求头和请求体的格式是否符合 API 文档要求。
  • 使用工具（如 Postman）验证请求格式是否正确。
  • 查看服务器日志，确认具体错误信息。

2. 401 Unauthorized

• 含义：未认证，通常缺少 token 或 token 无效。
• 常见原因：
  • 缺少认证信息（如 API 密钥、Token）。
  • 提供的认证信息无效或已过期。
  • 认证方式不被服务器支持。
• 排查方法：
  • 确认是否已正确添加认证信息（如在请求头中添加 Authorization 字段）。
  • 检查 Token 是否过期或被撤销。
  • 查看服务器返回的错误信息，确认认证失败的具体原因。

3. 403 Forbidden

• 含义：已认证，但没有权限访问该资源。
• 常见原因：
  • 用户权限不足（如普通用户访问管理员资源）。
  • IP 地址被限制访问。
  • 资源被服务器配置为禁止访问。
• 排查方法：
  • 确认当前用户是否具有访问该资源的权限。
  • 检查服务器的访问控制策略（如防火墙规则、IP 白名单）。
  • 查看服务器日志，确认权限拒绝的具体原因。

4. 404 Not Found

• 含义：请求的资源不存在。
• 常见原因：
  • URL 错误或拼写错误。
  • 请求的资源已被删除或移动。
  • 路由配置错误，服务器无法匹配到正确的资源。
• 排查方法：
  • 检查 URL 是否正确，确认资源路径是否拼写错误。
  • 确认请求的资源是否已被删除或移动。
  • 查看服务器的路由配置，确认是否正确匹配请求路径。

5. 405 Method Not Allowed

• 含义：请求方法不被允许（如 GET 接口用了 POST）。
• 常见原因：
  • 使用了错误的 HTTP 方法（如对只支持 GET 的接口使用了 POST）。
  • 服务器配置限制了某些 HTTP 方法。
• 排查方法：
  • 确认接口支持的 HTTP 方法，根据 API 文档调整请求方法。
  • 查看服务器配置，确认是否限制了某些 HTTP 方法。

6. 409 Conflict

• 含义：请求与服务器当前状态冲突（如重复创建资源）。
• 常见原因：
  • 尝试创建已存在的资源（如重复创建用户）。
  • 数据更新冲突（如同时修改同一资源）。
• 排查方法：
  • 确认是否尝试创建已存在的资源。
  • 检查数据更新逻辑，避免冲突。

7. 410 Gone

• 含义：资源已永久删除，不再可用。
• 常见原因：
  • 请求的资源已被永久删除。
  • 资源被标记为不再可用。
• 排查方法：
  • 确认请求的资源是否已被永久删除。
  • 检查服务器的资源管理策略，确认资源状态。

8. 422 Unprocessable Entity

• 含义：请求格式正确，但语义错误（如字段验证失败）。
• 常见原因：
  • 请求体中的字段不符合服务器的验证规则（如字段为空、格式不正确）。
  • 数据类型不匹配或超出范围。
• 排查方法：
  • 检查请求体中的字段是否符合 API 文档要求。
  • 查看服务器返回的错误信息，确认具体字段验证失败的原因。

9. 429 Too Many Requests

• 含义：请求频率过高，触发限流。
• 常见原因：
  • 客户端请求频率超过服务器设定的限制。
  • 服务器配置了限流策略（如每秒请求次数限制）。
• 排查方法：
  • 检查服务器的限流策略，确认请求频率限制。
  • 优化客户端请求逻辑，避免频繁请求。

---

二、HTTP 5xx 状态码（服务器错误）

5xx 状态码表示服务器内部错误，无法正常处理客户端的请求。以下是常见 5xx 状态码的详细分析：

1. 500 Internal Server Error

• 含义：服务器内部错误，通常是代码异常。
• 常见原因：
  • 后端代码中存在未捕获的异常。
  • 数据库查询失败或连接失败。
  • 第三方服务调用失败。
• 排查方法：
  • 查看服务器日志，定位具体的错误信息。
  • 检查后端代码，确认是否有未捕获的异常。
  • 检查数据库连接和查询逻辑，确认是否正常。

2. 502 Bad Gateway

• 含义：网关错误，通常是上游服务器无响应。
• 常见原因：
  • 上游服务器（如后端服务）不可用或返回无效响应。
  • 网关与上游服务器之间的网络问题。
• 排查方法：
  • 检查上游服务器的状态，确认是否正常运行。
  • 检查网关与上游服务器之间的网络连接，确认是否正常。

3. 503 Service Unavailable

• 含义：服务不可用，可能是服务器过载或维护中。
• 常见原因：
  • 服务器过载，无法处理更多请求。
  • 服务器正在进行维护。
• 排查方法：
  • 检查服务器负载，确认是否过载。
  • 查看服务器维护计划，确认是否在维护中。

4. 504 Gateway Timeout

• 含义：网关超时，通常是上游服务器响应超时。
• 常见原因：
  • 上游服务器响应时间过长，超过网关的超时设置。
  • 网关与上游服务器之间的网络延迟过高。
• 排查方法：
  • 检查上游服务器的响应时间，确认是否过长。
  • 调整网关的超时设置，适当增加超时时间。

---

三、总结建议

1. 客户端错误（4xx）

• 前端开发：确保请求格式、参数和认证信息符合 API 文档要求。
• 后端开发：提供详细的错误信息（如字段验证失败的具体原因），帮助客户端快速定位问题。

2. 服务器错误（5xx）

• 后端开发：确保代码中捕获所有异常，并记录详细的错误日志。
• 运维人员：监控服务器状态，及时发现并处理过载、网络问题等。

3. 排查方法

• 查看日志：无论是客户端还是服务器端，日志是排查问题的关键。
• 使用工具：如 Postman、Fiddler 等工具，帮助验证请求格式和响应内容。
• 检查配置：确认服务器和网关的配置是否正确，避免因配置错误导致问题。