HTTP Status Codes Reference

Status Code Categories

• 1xx Informational: The request was received and is being processed.
• 2xx Success: The request was successfully processed.
• 3xx Redirection: Further action is needed to complete the request.
• 4xx Client Error: The request itself contains a problem.
• 5xx Server Error: The server failed to process a valid request.

Commonly Confused Status Code Pairs

These codes look similar but serve different purposes. Mixing them up is a frequent source of bugs in API design, SEO, and debugging.

200 OK vs 204 No Content

• 200 - The response has a body. Use for standard GET and POST responses.
• 204 - The operation succeeded but there is no body to return. Ideal after a DELETE or PUT when no follow-up data is needed.
• Common mistake - Returning 200 with an empty object {} after a DELETE works, but 204 communicates intent more clearly.

301 vs 302 vs 307 vs 308 - Four Redirect Flavors

• 301 Moved Permanently - Permanent move. Search engines transfer authority and index to the new URL. Use for domain migrations and URL restructuring.
• 302 Found - Temporary move. Authority is not transferred. Use for A/B tests or maintenance pages.
• 307 Temporary Redirect - Same as 302 but preserves the HTTP method (e.g., POST stays POST). Safer than 302, which some clients silently downgrade to GET.
• 308 Permanent Redirect - Same as 301 but preserves the HTTP method. Use for permanently redirecting POST endpoints.
• Common mistake - Using 302 for a permanent move means search engines never migrate authority to the new URL, causing SEO loss.

401 Unauthorized vs 403 Forbidden

• 401 - "I don't know who you are." Authentication is required. Providing credentials may grant access.
• 403 - "I know who you are, but you're not allowed here." Authenticated but lacking permission. Sending credentials again won't help.
• Common mistake - Returning 403 to an unauthenticated user prevents the client from prompting a login flow.

404 Not Found vs 410 Gone

• 404 - Not currently found. May be temporary or permanent. Search engines will revisit.
• 410 - Permanently removed. Search engines de-index the URL quickly. Use 410 for content you've intentionally retired.
• Common mistake - Leaving a retired page at 404 keeps it in search results for much longer than a 410 would.

500 vs 502 vs 503 vs 504 - Four Server Error Flavors

• 500 Internal Server Error - Application code threw an exception. The origin server is to blame; time to debug.
• 502 Bad Gateway - A gateway (Nginx, CDN) received an invalid response from the upstream backend. Suspect a crashed or misconfigured backend.
• 503 Service Unavailable - Temporarily overloaded or down for maintenance. Pair with a Retry-After header.
• 504 Gateway Timeout - The gateway gave up waiting for a response from the upstream. Unlike 502, the backend never replied at all.
• Common mistake - Serving a maintenance page with 200 lets search engines index the maintenance page as real content. Use 503 + Retry-After instead.

400 Bad Request vs 422 Unprocessable Entity

• 400 - The request syntax is malformed. JSON failed to parse, required headers are missing, etc.
• 422 - The syntax is fine, but the semantics are invalid. Required fields missing, validation rules violated.
• Common mistake - Using 400 for all input errors prevents clients from distinguishing a parse error from a validation failure.

Frequently Asked Questions

What is the difference between 401 and 403?

401 (Unauthorized) means authentication is required (not logged in), while 403 (Forbidden) means you are authenticated but lack permission for the resource.

What is the difference between 301 and 302?

301 (Moved Permanently) is a permanent move, 302 (Found) is temporary. For SEO, use 301 when permanent so search engines transfer authority to the new URL.

What is the difference between 500 and 502?

500 (Internal Server Error) is a generic server-side error, while 502 (Bad Gateway) means a gateway/proxy received an invalid response from the upstream backend.

Is 418 I'm a teapot a real standard?

It is a joke RFC (RFC 2324) defined on April Fools' Day 1998, but it is actually registered with IANA. It is not for production use, though some services use it as an Easter egg.