HTTP Status Codes: The Definitive Reference for Developers

HTTP 状态码是 Web 的语言。如果你只认识 200 和 404，那你还有 58 个要学。

Every API you build, every request you debug, every error you handle — it all comes back to HTTP status codes. Let me give you the reference I wish I had on day one.

2xx: Success

Code	Name	When to Use
200	OK	Standard success response
201	Created	Resource created (POST)
204	No Content	Success but no body (DELETE)

201 vs 200 — The Debate

When creating a resource:

• 200 OK with the created resource in the body — common in REST APIs
• 201 Created with a Location header — technically more correct

Both work. Pick one and be consistent.

3xx: Redirection

Code	Name	When to Use
301	Moved Permanently	URL changed forever (SEO: passes link equity)
302	Found	Temporary redirect
304	Not Modified	Cache hit — resource unchanged
307	Temporary Redirect	Like 302 but preserves HTTP method
308	Permanent Redirect	Like 301 but preserves HTTP method

301 vs 308

• 301 — Redirects GET, but browsers may change POST to GET
• 308 — Redirects ALL methods as-is

For APIs, always use 308. For websites, 301 is fine.

4xx: Client Errors

Code	Name	When to Use
400	Bad Request	Malformed request body or parameters
401	Unauthorized	Not authenticated (missing/invalid token)
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource doesn't exist
405	Method Not Allowed	Wrong HTTP method (POST instead of GET)
409	Conflict	Resource conflict (duplicate email)
422	Unprocessable Entity	Valid syntax but semantic errors
429	Too Many Requests	Rate limit exceeded

401 vs 403 — The Confusion

• 401 — "I don't know who you are" (authenticate first)
• 403 — "I know who you are, but you can't do this"

422 vs 400 — The Debate

• 400 — The request is syntactically wrong (can't parse JSON)
• 422 — The request is syntactically correct but semantically wrong (email field has invalid format)

5xx: Server Errors

Code	Name	When to Use
500	Internal Server Error	Generic server failure
502	Bad Gateway	Upstream server returned invalid response
503	Service Unavailable	Server is down or overloaded
504	Gateway Timeout	Upstream server didn't respond in time

The Codes Nobody Uses (But Should)

• 418 I'm a Teapot — RFC 2324 (April Fools). Actually implemented by some coffee machines.
• 451 Unavailable For Legal Reasons — Censored content
• 503 Service Unavailable with Retry-After header — Graceful degradation

API Design Best Practices

1. Always return a body with error responses — Include a message explaining what went wrong
2. Use 422 for validation errors — Return field-level error details
3. Include Rate Limit headers — X-RateLimit-Remaining, Retry-After
4. Don't use 200 for errors — Some APIs return 200 OK with {"error": "..."}. Don't.

Debugging Tips

When debugging API issues, use a tool that shows the full HTTP response — headers, body, and status code. Understanding the exact status code tells you WHERE the problem is:

• 4xx → Your client code is wrong
• 5xx → The server is broken
• 3xx → The URL changed

Test your API endpoints and inspect status codes with our free HTTP Status Code Reference — searchable, filterable, with real-world examples.