HTTP 状态码：开发者完全参考指南

HTTP 状态码是服务器响应客户端请求时返回的三位数字。理解这些状态码对于调试 API、构建健壮的 Web 应用至关重要。本完整 HTTP 状态码参考指南涵盖了你在实际开发中会遇到的所有状态码。

使用我们的 HTTP 状态码工具快速查询 →

1xx — 信息响应

表示服务器已接收请求，正在继续处理。

2xx — 成功

最常见的类别，表示请求已成功处理。

3xx — 重定向

客户端需要执行额外操作才能完成请求。

4xx — 客户端错误

问题出在客户端。

5xx — 服务器错误

服务器无法完成请求。

API 状态码最佳实践

选择正确的状态码让 API 更直观易用。

// REST API Status Code Guidelines

// Creating a resource
POST /api/users → 201 Created (with Location header)

// Successful read
GET /api/users/123 → 200 OK

// Successful update
PUT /api/users/123 → 200 OK (with updated resource)
PATCH /api/users/123 → 200 OK

// Successful delete
DELETE /api/users/123 → 204 No Content

// Validation error
POST /api/users (invalid data) → 422 Unprocessable Entity
{
  "error": "Validation failed",
  "details": [
    { "field": "email", "message": "Invalid email format" }
  ]
}

// Authentication required
GET /api/admin → 401 Unauthorized
{ "error": "Authentication required" }

// No permission
GET /api/admin (as regular user) → 403 Forbidden
{ "error": "Insufficient permissions" }

// Resource not found
GET /api/users/999 → 404 Not Found
{ "error": "User not found" }

// Rate limit exceeded
GET /api/search → 429 Too Many Requests
Retry-After: 60
{ "error": "Rate limit exceeded", "retry_after": 60 }

常见调试场景

排查 HTTP 问题时，状态码是最重要的线索。

CORS Errors (Browser shows "blocked by CORS")

The browser blocks the request, but the actual HTTP status may be hidden. Check server logs. Ensure your server sends the correct Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers headers.

502 Bad Gateway on Deployment

Your reverse proxy (Nginx, Cloudflare) can't reach your application server. Check: Is the app process running? Is it listening on the correct port? Are there firewall rules blocking the connection?

# Check if your app is running
ps aux | grep node

# Check if it's listening on the expected port
netstat -tlnp | grep 3000

# Check Nginx error logs
tail -f /var/log/nginx/error.log

504 Gateway Timeout

The upstream server is too slow. Common causes: slow database queries, external API timeouts, or large file processing. Solutions: optimize queries, add timeouts to external calls, use background jobs for heavy tasks.

429 Rate Limiting

// Implementing exponential backoff in JavaScript
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);
    if (response.status !== 429) return response;

    const retryAfter = response.headers.get('Retry-After');
    const delay = retryAfter
      ? parseInt(retryAfter) * 1000
      : Math.pow(2, i) * 1000; // 1s, 2s, 4s

    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error('Max retries exceeded');
}

常见问题

401 和 403 有什么区别？

401 = 缺少认证凭据。403 = 已认证但没有权限。

何时使用 200 vs 201？

200 用于成功的请求，201 用于成功创建新资源。

418 I'm a Teapot 是什么意思？

1998 年的愚人节玩笑（RFC 2324），服务器拒绝煮咖啡，因为它是茶壶。

301 和 302 对 SEO 有什么影响？

301 = 永久重定向（传递 SEO 权重）。302 = 临时重定向。

如何处理 429 错误？

检查 Retry-After 头部，实现指数退避重试。

理解 HTTP 状态码是开发和调试的基础。使用我们的工具快速查询。

使用 HTTP 状态码工具查询 →