HTTP 状态码详解指南

📋 本文档详细介绍所有HTTP状态码及其排查方法

📊 HTTP状态码分类概览

flowchart TB subgraph HTTP状态码体系 A1["🌐 1xx 信息性状态码"] A2["✅ 2xx 成功状态码"] A3["🔄 3xx 重定向状态码"] A4["❌ 4xx 客户端错误码"] A5["🚨 5xx 服务器错误码"] end classDef info fill:#3498db,color:#fff classDef success fill:#27ae60,color:#fff classDef redirect fill:#f39c12,color:#fff classDef clientErr fill:#e67e22,color:#fff classDef serverErr fill:#c0392b,color:#fff class A1 info class A2 success class A3 redirect class A4 clientErr class A5 serverErr
分类 颜色 语义
🌐 1xx 信息性 🔵 蓝色 #3498db 信息传递，请求处理中
✅ 2xx 成功 🟢 绿色 #27ae60 请求成功完成
🔄 3xx 重定向 🟡 橙色 #f39c12 需要进一步操作
❌ 4xx 客户端错误 🟠 橙色 #e67e22 客户端请求有误
🚨 5xx 服务器错误 🔴 红色 #c0392b 服务器处理失败

🌐 1xx 信息性状态码 (Information)

状态码 名称 说明
100 Continue 服务器收到请求的初始部分，客户端应继续发送请求
101 Switching Protocols 服务器同意切换到请求的协议
102 Processing 服务器已收到请求并正在处理（WebDAV）
103 Early Hints 服务器在最终响应之前返回响应头

🎯 常见场景与排查

100 Continue

  • 🐧 使用场景：客户端有大量数据要发送，先确认服务器是否接受
  • 🔧 排查方法：
    # 检查请求头是否包含 Expect: 100-continue
curl -I -H "Expect: 100-continue" https://example.com/api/upload

101 Switching Protocols

  • 🐧 使用场景：WebSocket升级、HTTP/2升级
  • 🔧 排查方法：
    # 检查WebSocket握手
curl -i --include \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  https://example.com/ws

✅ 2xx 成功状态码 (Success)

状态码 名称 说明
200 OK 请求成功
201 Created 请求成功并创建了新资源
202 Accepted 请求已接受，但处理尚未完成
204 No Content 请求成功，但返回没有内容
206 Partial Content 部分内容成功（断点续传）

🎯 常见场景与排查

200 OK

flowchart LR A["📤 客户端请求"] --> B["🔧 服务器处理"] B --> C{处理结果} C -->|成功| D["✅ 返回 200 OK"] C -->|部分成功| E["⚠️ 返回 200 + 警告"] classDef request fill:#3498db,color:#fff classDef process fill:#f39c12,color:#fff classDef success fill:#27ae60,color:#fff classDef warning fill:#e67e22,color:#fff class A request class B process class C process class D success class E warning
  • 🔧 排查方法：
    # 检查完整响应
curl -i https://example.com/api/data

# 验证JSON响应格式
curl -s https://example.com/api/data | jq .

201 Created

  • 🐧 使用场景：POST请求创建资源
  • 🔧 排查方法：
    # 检查响应头中的 Location
curl -i -X POST https://example.com/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"张三"}'

# 预期响应头：Location: /api/users/123

204 No Content

  • 🐧 使用场景：DELETE请求成功、OPTIONS预检请求
  • 🔧 排查方法：
    # DELETE请求验证
curl -i -X DELETE https://example.com/api/users/123
# 响应应该是空body，状态码204

206 Partial Content

  • 🐧 使用场景：断点续传、视频流播放
  • 🔧 排查方法：
    # 检查Content-Range头
curl -i \
  -H "Range: bytes=0-99" \
  https://example.com/largefile.zip

# 验证Accept-Ranges头
curl -I https://example.com/largefile.zip
# 应包含：Accept-Ranges: bytes

🔄 3xx 重定向状态码 (Redirection)

状态码 名称 说明
300 Multiple Choices 多种选择，需客户端选择一个
301 Moved Permanently 永久重定向
302 Found 临时重定向（⚠️ 可能改变请求方法）
303 See Other 重定向到另一个URI（POST转GET）
304 Not Modified 使用缓存（未修改）
307 Temporary Redirect 临时重定向（保持方法不变）
308 Permanent Redirect 永久重定向（保持方法不变）

🎯 常见场景与排查

301 vs 302 vs 307 vs 308 对比

flowchart TB A["📤 原始请求"] --> B{状态码类型} B -->|301/302| C["⚠️ 可能改变方法"] B -->|307/308| D["✅ 方法保持不变"] C --> E["🔍 301/302 问题排查"] D --> F["✅ 307/308 推荐使用"] classDef request fill:#3498db,color:#fff classDef decision fill:#9b59b6,color:#fff classDef warning fill:#e67e22,color:#fff classDef success fill:#27ae60,color:#fff classDef info fill:#f39c12,color:#fff class A request class B decision class C warning class D success class E info class F success
状态码 方法变化 缓存性 适用场景
301 可能改变 可缓存 永久迁移（旧版兼容）
302 可能改变 不推荐缓存 临时重定向（旧版兼容）
303 总是 GET 不缓存 POST重定向为GET
307 保持不变 不缓存 临时重定向（保持方法）
308 保持不变 可缓存 永久重定向（保持方法）

301 Moved Permanently 排查

# 检查重定向链
curl -I -L https://example.com/old-path

# 验证永久重定向
curl -i https://example.com/old-path

# 期望输出应包含：
# HTTP/1.1 301 Moved Permanently
# Location: https://example.com/new-path

302/307 临时重定向排查

flowchart LR A["📤 POST /api/submit"] --> B["🔄 302 Found"] B --> C["📥 重定向到 /result"] C --> D["📋 显示结果页面"] classDef request fill:#3498db,color:#fff classDef redirect fill:#f39c12,color:#fff classDef success fill:#27ae60,color:#fff class A request class B redirect class C redirect class D success 
# 检查是否保持POST方法（307）
curl -i -X POST https://example.com/submit \
  -d "data=value"

# 对比302和307行为差异
# 302：可能变GET
# 307：必须保持POST

304 Not Modified 排查

# 检查缓存命中
curl -i \
  -H "If-None-Match: \"abc123\"" \
  -H "If-Modified-Since: Mon, 18 May 2026 10:00:00 GMT" \
  https://example.com/api/data

# 期望响应：
# HTTP/1.1 304 Not Modified
# （无响应体）

⚠️ 304 排查要点：

  • 检查请求头 If-None-Match 或 If-Modified-Since
  • 确认 ETag 匹配
  • 验证 CDN/浏览器缓存配置

❌ 4xx 客户端错误状态码 (Client Errors)

状态码 名称 说明
400 Bad Request 请求语法错误或参数错误
401 Unauthorized 需要身份认证（未认证）
403 Forbidden 认证后无权限（已认证但无权限）
404 Not Found 资源不存在
405 Method Not Allowed 请求方法不允许
408 Request Timeout 请求超时
409 Conflict 资源冲突
410 Gone 资源已永久删除
413 Payload Too Large 请求体过大
414 URI Too Long URI过长
415 Unsupported Media Type 不支持的媒体类型
422 Unprocessable Entity 请求格式正确但语义错误
429 Too Many Requests 请求过于频繁

🎯 4xx 错误排查流程

flowchart TB A["❌ 收到 4xx 错误"] --> B{状态码类型} B -->|400| C["🔍 检查请求语法"] B -->|401| D["🔐 检查认证信息"] B -->|403| E["🔑 检查权限配置"] B -->|404| F["🗂️ 检查资源路径"] B -->|429| G["⏱️ 检查限流策略"] C --> C1["✅ 参数格式正确"] C1 --> C2["❓ 语义是否正确?"] C2 -->|是| C3["📝 检查请求头"] C2 -->|否| C4["⚠️ 业务逻辑问题"] D --> D1["📋 是否提供Token?"] D1 -->|否| D2["🔑 添加Authorization头"] D1 -->|是| D3["✅ Token是否有效?"] D3 -->|否| D4["🔄 刷新Token"] E --> E1["👤 是否已认证?"] E1 -->|否| E2["🔐 先完成认证"] E1 -->|是| E3["🔑 检查ACL/RBAC配置"] F --> F1["🗂️ 路径是否正确?"] F1 -->|是| F2["📦 检查资源是否删除"] F1 -->|否| F3["✏️ 修正请求路径"] G --> G1["⏱️ 等待冷却时间"] G1 --> G2["📉 降低请求频率"] classDef error fill:#c0392b,color:#fff classDef category fill:#e67e22,color:#fff classDef action fill:#3498db,color:#fff classDef success fill:#27ae60,color:#fff classDef warning fill:#f39c12,color:#fff classDef question fill:#9b59b6,color:#fff class A error class B category class C action class D action class E action class F action class G action class C1 success class C2 question class C3 action class C4 warning class D1 question class D2 action class D3 question class D4 action class E1 question class E2 action class E3 action class F1 question class F2 action class F3 action class G1 action class G2 action

400 Bad Request 详细排查

flowchart LR A["📤 请求"] --> B{400错误原因} B -->|语法错误| C["🔧 JSON格式错误"] B -->|参数错误| D["📝 必填参数缺失"] B -->|值无效| E["⚠️ 参数值不合法"] C --> C1["✅ 修复JSON语法"] D --> D1["✅ 补充必填参数"] E --> E1["✅ 使用有效值"] classDef request fill:#3498db,color:#fff classDef cause fill:#c0392b,color:#fff classDef fix fill:#e67e22,color:#fff classDef success fill:#27ae60,color:#fff class A request class B cause class C fix class D fix class E fix class C1 success class D1 success class E1 success

🔧 排查命令：

# 检查JSON语法
curl -i -X POST https://example.com/api/data \
  -H "Content-Type: application/json" \
  -d '{"name": "张三", "age": 25}'

# 验证JSON格式
echo '{"name": "张三", "age": 25}' | jq .

# 检查参数校验错误信息
curl -s https://example.com/api/data | jq .error

⚠️ 常见原因：

  • JSON语法错误（缺少引号、逗号）
  • 参数类型错误（字符串传了数字）
  • 参数值超出范围
  • 必填参数缺失

401 Unauthorized 详细排查

flowchart LR A["🔐 认证流程"] --> B{是否提供凭证} B -->|否| C["📝 添加凭证"] B -->|是| D{凭证有效?} D -->|否| E["🔄 重新获取Token"] D -->|是| F["✅ 认证成功"] C --> C1["Bearer Token / Basic Auth"] E --> E1["检查Token过期时间"] classDef auth fill:#9b59b6,color:#fff classDef question fill:#e67e22,color:#fff classDef action fill:#3498db,color:#fff classDef success fill:#27ae60,color:#fff classDef warning fill:#f39c12,color:#fff class A auth class B question class C action class D question class E action class F success class C1 warning class E1 warning

🔧 排查命令：

# 检查是否携带Token
curl -i https://example.com/api/protected

# 添加Bearer Token
curl -i \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://example.com/api/protected

# 使用Basic Auth
curl -i -u "username:password" \
  https://example.com/api/basic-auth

# 检查Token内容
curl -s https://example.com/api/token/verify \
  -H "Authorization: Bearer <token>" | jq .

⚠️ 常见原因：

  • 未提供 Authorization 头
  • Token过期
  • Token格式错误（Bearer 拼写错误）
  • 签名验证失败

403 Forbidden 详细排查

flowchart TB A["🔑 403错误排查"] --> B{是否已认证} B -->|否| C["🔐 完成401认证"] B -->|是| D{权限是否足够?} D -->|否| E["📋 检查角色配置"] D -->|是| F["🔍 其他403原因"] E --> E1["👤 分配必要角色"] F --> F1["🔎 检查IP白名单"] F1 --> F2["🔎 检查服务账号权限"] classDef error fill:#c0392b,color:#fff classDef question fill:#e67e22,color:#fff classDef action fill:#3498db,color:#fff classDef success fill:#27ae60,color:#fff classDef warning fill:#f39c12,color:#fff class A error class B question class C action class D question class E action class F action class E1 success class F1 warning class F2 warning

🔧 排查命令：

# 检查当前用户权限
curl -i \
  -H "Authorization: Bearer <token>" \
  https://example.com/api/admin

# 检查响应头信息
curl -i https://example.com/api/admin

# 检查IAM策略
aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::123456789:user/example \
  --action-names api:AdminAccess \
  --resource-arns arn:aws:api::*

# 检查RBAC配置
kubectl auth can-i get pods --as=system:serviceaccount:default:my-app

⚠️ 常见原因：

  • 角色/权限不足
  • IP不在白名单
  • 缺少特定操作权限
  • 资源策略拒绝访问

404 Not Found 详细排查

flowchart LR A["🔍 404排查流程"] --> B{资源存在?} B -->|是| C["🗂️ 路径正确?"] B -->|否| D["📦 资源已删除?"] C -->|否| E["✏️ 修正路径"] C -->|是| F["🔧 其他配置问题"] D -->|是| G["📝 更新文档"] classDef error fill:#c0392b,color:#fff classDef question fill:#e67e22,color:#fff classDef action fill:#3498db,color:#fff classDef success fill:#27ae60,color:#fff classDef warning fill:#f39c12,color:#fff class A error class B question class C question class D question class E success class F warning class G warning

🔧 排查命令：

# 检查资源是否存在
curl -i https://example.com/api/users/123

# 检查路由配置
nginx -t
apachectl -t

# 查看访问日志
tail -f /var/log/nginx/access.log | grep 404

# 检查URL重写规则
# nginx.conf
# location /api/ {
#     rewrite ^/api/(.*) /backend/$1 break;
# }

# 对比不同路径
curl -i https://example.com/api/v1/users
curl -i https://example.com/api/v2/users

⚠️ 常见原因：

  • 资源已删除/迁移
  • URL路径拼写错误
  • 路由配置错误
  • 大小写不匹配（Linux区分大小写）

429 Too Many Requests 详细排查

flowchart TB A["⏱️ 限流错误排查"] --> B{是否触发限流} B --> C["📋 检查响应头"] C --> D{Retry-After存在?} D -->|是| E["⏳ 等待指定时间"] D -->|否| F["🔍 了解限流策略"] E --> G["📉 降低请求频率"] F --> G G --> H["✅ 实现退避算法"] H --> I["🔄 重试请求"] classDef error fill:#c0392b,color:#fff classDef question fill:#e67e22,color:#fff classDef action fill:#3498db,color:#fff classDef success fill:#27ae60,color:#fff classDef warning fill:#f39c12,color:#fff class A error class B question class C action class D question class E warning class F action class G action class H success class I action

🔧 排查命令：

# 检查限流响应头
curl -i https://example.com/api/data

# 响应头示例：
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 0
# X-RateLimit-Reset: 1623456789
# Retry-After: 3600

# 指数退避重试示例
#!/bin/bash
for i in {1..5}; do
  response=$(curl -s -o /dev/null -w "%{http_code}" https://example.com/api/data)
  if [ "$response" != "429" ]; then
    echo "成功: $response"
    break
  fi
  wait_time=$((2 ** i))
  echo "等待 ${wait_time}秒后重试..."
  sleep $wait_time
done

⚠️ 常见原因：

  • 请求频率超出限制
  • 并发连接数超限
  • 配额用尽

🚨 5xx 服务器错误状态码 (Server Errors)

状态码 名称 说明
500 Internal Server Error 服务器内部错误
501 Not Implemented 功能未实现
502 Bad Gateway 网关错误（上游服务器问题）
503 Service Unavailable 服务不可用（过载/维护）
504 Gateway Timeout 网关超时
505 HTTP Version Not Supported HTTP版本不支持

🎯 5xx 错误排查流程

flowchart TB A["🚨 收到 5xx 错误"] --> B{状态码类型} B -->|500| C["🔧 应用层错误"] B -->|502| D["🌐 网关/代理问题"] B -->|503| E["⏰ 服务过载/维护"] B -->|504| F["⏱️ 上游超时"] C --> C1["📝 查看应用日志"] C1 --> C2["🔍 定位异常堆栈"] C2 --> C3["✅ 修复代码/配置"] D --> D1["🔙 检查上游服务"] D1 --> D2["📊 检查服务健康"] D2 --> D3["🔧 修复网络/服务"] E --> E1["📈 检查负载"] E1 --> E2["🔄 扩容/等待恢复"] F --> F1["⏱️ 调整超时配置"] F1 --> F2["📉 优化上游响应"] classDef error fill:#c0392b,color:#fff classDef category fill:#e67e22,color:#fff classDef action fill:#3498db,color:#fff classDef success fill:#27ae60,color:#fff classDef warning fill:#f39c12,color:#fff class A error class B category class C action class D action class E action class F action class C1 action class C2 action class C3 success class D1 action class D2 action class D3 success class E1 action class E2 success class F1 action class F2 success

500 Internal Server Error 详细排查

🔧 排查命令：

# 查看应用日志
tail -f /var/log/nginx/error.log
tail -f /var/log/apache2/error.log

# 查看应用日志
tail -f /var/log/myapp/application.log

# 检查进程状态
ps aux | grep -E "nginx|apache|node|python|java"

# 检查系统资源
df -h
free -m
top -bn1 | head -20

# 常见500错误原因
# 1. 代码异常 - 检查应用日志
# 2. 权限问题 - ls -la /var/www/
# 3. 依赖缺失 - pip list / npm list
# 4. 配置错误 - 检查配置文件语法

⚠️ 常见原因：

  • 代码异常未捕获
  • 依赖服务连接失败
  • 权限配置错误
  • 配置文件语法错误
  • 资源耗尽（内存/磁盘）

502 Bad Gateway 详细排查

flowchart LR A["📤 客户端"] --> B["🔀 Nginx/代理"] B --> C{502错误} C --> D["🔙 检查上游服务"] D --> E["🔧 修复上游问题"] B -.->|"上游无响应"| F["⚠️ 上游服务down"] B -.->|"错误响应"| G["⚠️ 上游返回错误"] B -.->|"协议不匹配"| H["⚠️ 版本不兼容"] classDef client fill:#3498db,color:#fff classDef gateway fill:#9b59b6,color:#fff classDef error fill:#c0392b,color:#fff classDef action fill:#e67e22,color:#fff classDef warning fill:#f39c12,color:#fff class A client class B gateway class C error class D action class E success class F warning class G warning class H warning

🔧 排查命令：

# 检查上游服务状态
curl -i http://localhost:8080/health

# 检查nginx错误日志
tail -f /var/log/nginx/error.log | grep 502

# 检查上游服务日志
tail -f /var/log/backend/error.log

# 测试上游服务直接连接
curl -i http://127.0.0.1:8080/api/data

# 检查nginx upstream配置
# nginx.conf
# upstream backend {
#     server 127.0.0.1:8080;
#     server 127.0.0.1:8081 backup;
# }

# 检查网络连接
netstat -an | grep :8080
ss -tlnp | grep :8080

# 检查防火墙
iptables -L -n | grep 8080

⚠️ 常见原因：

  • 上游服务未启动
  • 上游服务崩溃
  • Nginx无法连接到上游
  • 上游响应超时
  • 协议版本不匹配

503 Service Unavailable 详细排查

flowchart TB A["⏰ 503错误"] --> B{原因判断} B -->|"过载"| C["📈 扩容"] B -->|"维护"| D["🔧 结束维护"] B -->|"健康检查失败"| E["❤️ 修复健康检查"] C --> C1["🔄 增加实例"] C1 --> C2["📊 负载下降"] D --> D1["✅ 恢复正常"] E --> E1["🔧 修复应用"] classDef error fill:#c0392b,color:#fff classDef question fill:#e67e22,color:#fff classDef action fill:#3498db,color:#fff classDef success fill:#27ae60,color:#fff class A error class B question class C action class D action class E action class C1 action class C2 success class D1 success class E1 action

🔧 排查命令：

# 检查服务健康状态
curl -i https://example.com/health

# 检查负载情况
uptime
w
top -bn1

# 查看请求队列
netstat -an | grep ESTABLISHED | wc -l

# Kubernetes健康检查
kubectl get pods
kubectl describe pod <pod-name> | grep -A 10 "Conditions"

# 启用维护页面（nginx）
# error_page 503 /maintenance.html;
# location = /maintenance.html {
#     internal;
# }

⚠️ 常见原因：

  • 服务器过载
  • 维护中
  • 达到最大连接数
  • 资源耗尽

504 Gateway Timeout 详细排查

🔧 排查命令：

# 检查上游响应时间
time curl -i https://example.com/api/slow-endpoint

# 检查nginx超时配置
# proxy_connect_timeout 60s;
# proxy_send_timeout 60s;
# proxy_read_timeout 60s;

# 检查慢查询
# MySQL: SHOW FULL PROCESSLIST;
# PostgreSQL: SELECT * FROM pg_stat_activity;

# 使用strace跟踪
strace -t -f -p <nginx_pid>

# 增加超时时间测试
curl -i \
  --max-time 300 \
  https://example.com/api/heavy-task

⚠️ 常见原因：

  • 上游处理时间过长
  • 网络延迟
  • 慢查询阻塞
  • 第三方服务响应慢

🛠️ 通用排查工具箱

📊 常用诊断命令

# 检查请求完整信息
curl -i -v https://example.com/api/data

# 检查响应头
curl -I https://example.com/api/data

# 追踪重定向
curl -L -I https://example.com/redirect

# 检查SSL/TLS
curl -Iv --tlsv1.2 https://example.com

# 检查DNS解析
dig example.com
nslookup example.com

# 检查网络路由
traceroute example.com
tracert example.com  # Windows

# 检查端口开放
nc -zv example.com 443
telnet example.com 443

# 检查连接状态
netstat -an | grep :80
ss -tlnp | grep :80

# 详细请求日志分析
tail -f /var/log/nginx/access.log | grep -E "5xx|404|401"

🔧 API调试工具

# JSON格式化输出
curl -s https://api.example.com/data | jq .

# 请求计时分析
curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTotal: %{time_total}s\n" \
  -o /dev/null -s https://example.com/api

# 查看HTTP版本和详情
curl -i --http2 https://example.com/api

# 模拟不同客户端
curl -i -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  https://example.com/

📋 状态码速查表

分类 状态码 严重程度 优先排查方向
🌐 1xx 100,101,102,103 ✅ 低 正常流程，通常不需要排查
✅ 2xx 200,201,202,204,206 ✅ 正常 无错误，无需处理
🔄 3xx 300,301,302,303,304,307,308 ⚠️ 注意 检查重定向循环、缓存配置
❌ 4xx 400,401,403,404,405,409,410,413,422,429 ⚠️ 中 检查请求、认证、权限
🚨 5xx 500,501,502,503,504,505 🚨 高 检查日志、负载、网络

🎯 快速诊断决策树

flowchart TB A["🔍 HTTP响应分析"] --> B{HTTP状态码} B -->|2xx| Z["✅ 请求成功"] B -->|3xx| Y{重定向类型} Y -->|304| Y1["📦 使用缓存"] Y -->|其他| Y2["🔄 检查重定向目标"] B -->|4xx| X{错误类型} X -->|401| X1["🔐 添加认证"] X -->|403| X2["🔑 检查权限"] X -->|404| X3["🗂️ 确认资源存在"] X -->|429| X4["⏱️ 限流等待"] B -->|5xx| W{错误类型} W -->|500| W1["📝 查看应用日志"] W -->|502| W2["🔙 检查上游服务"] W -->|503| W3["📈 检查服务状态"] W -->|504| W4["⏱️ 调整超时配置"] classDef start fill:#9b59b6,color:#fff classDef decision fill:#3498db,color:#fff classDef success fill:#27ae60,color:#fff classDef error fill:#c0392b,color:#fff classDef warning fill:#e67e22,color:#fff classDef info fill:#f39c12,color:#fff class A start class B decision class Z success class Y decision class Y1 info class Y2 warning class X decision class X1 error class X2 error class X3 error class X4 error class W decision class W1 error class W2 error class W3 error class W4 error

📝 文档创建日期：2026/05/18
🔧 最后更新时间：2026/05/18

posted @ 2026-05-19 10:33  RK5123153  阅读(7)  评论(0)    收藏  举报