HTTP Status Code Reference

Your load balancer returns 502 and you need to know: is the backend down (502 Bad Gateway) or just slow (504 Gateway Timeout)? Should your retry logic handle this, or should you alert? The difference between codes that look similar — 301 vs 308, 401 vs 403, 502 vs 503 — matters for caching behavior, SEO, and error handling.

Why This Reference (Not the HTTP Status Code Reference)

PureDevTools has multiple HTTP status tools. This one is a searchable, filterable list optimized for quick lookups — type a code number or keyword, get the description and use case instantly. The HTTP Status Code Reference includes more detailed example response headers. Use whichever is faster for your workflow.

What Are HTTP Status Codes?

HTTP status codes are three-digit numeric codes returned by a server in response to every HTTP request. They tell the client whether the request was successful, resulted in an error, or requires additional action. Every status code belongs to one of five classes defined by its first digit.

HTTP/1.1 200 OK
HTTP/1.1 404 Not Found
HTTP/1.1 301 Moved Permanently

Status codes are defined in the HTTP specification (RFC 9110 and related RFCs) and maintained by IANA. Understanding them is essential for building, debugging, and consuming APIs and web services.

The Five Categories

1xx Informational Codes

Informational responses are provisional — they tell the client the request was received and processing is continuing. You rarely see them directly; they are typically handled transparently by HTTP clients and servers.

100 Continue is the most common 1xx code, used with the Expect: 100-continue header to avoid sending a large request body if the server would reject it.

101 Switching Protocols is the code used during a WebSocket handshake — the connection upgrades from HTTP to the WebSocket protocol.

103 Early Hints is a modern performance optimization: the server sends preliminary Link headers so the browser can preload resources before the full response arrives.

2xx Success Codes

The 2xx class indicates success, but each code conveys a different nuance:

• 200 OK — The default success. Use it when returning a requested resource.
• 201 Created — A resource was created. Always include a Location header pointing to the new resource.
• 202 Accepted — The request was queued for asynchronous processing (email sends, video encoding, batch jobs).
• 204 No Content — Success with no body. Perfect for DELETE operations and autosave endpoints.
• 206 Partial Content — The response is a partial range. Essential for video streaming and resumable downloads.

# REST API conventions
GET  /users/42     → 200 OK  (resource returned)
POST /users        → 201 Created + Location: /users/42
DELETE /users/42   → 204 No Content
PUT  /users/42     → 200 OK (or 204 if no body needed)

3xx Redirection Codes

Redirection responses instruct clients to take additional action to complete the request. The Location header specifies where to redirect.

Permanent vs. Temporary Redirects

SEO tip: Use 301 for permanent URL changes — search engines transfer “link equity” to the new URL. Use 302 for temporary redirects that you intend to revert.

The Post/Redirect/Get (PRG) Pattern

A 303 See Other is the correct response after a successful form submission. Without it, refreshing the result page would resubmit the form:

POST /checkout   → 303 See Other  → Location: /order/12345
GET  /order/12345 → 200 OK

304 Not Modified and Caching

304 Not Modified is the caching workhorse. When a browser has a cached resource, it sends a conditional request:

GET /style.css
If-None-Match: "abc123"

→ 304 Not Modified  (use cache)
→ 200 OK + new body (cache stale, use new version)

4xx Client Error Codes

Client errors mean the request itself is wrong. The client needs to fix the request before retrying. The distinction between individual 4xx codes is important for API design:

Authentication vs. Authorization

• 401 Unauthorized — Not authenticated. The client must log in / provide valid credentials. (The name is misleading — it means “unauthenticated”.)
• 403 Forbidden — Authenticated but not authorized. The client has valid credentials but lacks permission. Re-authenticating won’t help.

// 401 — missing or invalid token
{ "error": "Authentication required", "code": "UNAUTHENTICATED" }

// 403 — valid token, wrong role
{ "error": "Admin access required", "code": "FORBIDDEN" }

The Most Important 4xx Codes for API Design

400 Bad Request — Use for syntactically invalid requests (malformed JSON, wrong data types).

422 Unprocessable Content — Use for semantically invalid requests that pass syntax checks (valid JSON, but business rules fail — duplicate email, invalid date range). This distinction between 400 and 422 is debated; many APIs use 400 for both.

409 Conflict — Use when the request conflicts with server state (duplicate record, optimistic locking conflict, version mismatch).

429 Too Many Requests — Rate limiting. Always include Retry-After to tell the client when to retry:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

404 vs. 410 — Use 404 when you don’t know if the resource ever existed. Use 410 Gone when you know the resource existed but was permanently deleted — search engines delist 410 pages faster.

The Famous Ones

418 I’m a Teapot (RFC 2324) was defined in an April Fools’ RFC in 1998. Surprisingly, it’s now used by some servers to signal intentional request refusal, and has been preserved in the HTTP specification.

451 Unavailable For Legal Reasons is named after Ray Bradbury’s Fahrenheit 451. Used for content removed due to legal demands (DMCA takedowns, court orders, government censorship).

5xx Server Error Codes

Server errors mean something went wrong on the server side, not with the request. The client can generally retry later.

Gateway Errors

When you have a reverse proxy (nginx, HAProxy, AWS ALB) in front of your application server:

• 502 Bad Gateway — The proxy got an invalid response from the upstream. Usually means the app server is down or crashed.
• 503 Service Unavailable — The server is temporarily unavailable (maintenance, overloaded). Use Retry-After to indicate when to retry.
• 504 Gateway Timeout — The upstream server didn’t respond in time. The app server is reachable but too slow.

Client → nginx → app server

502: app server returned garbage / crashed
503: nginx says "too busy" or "maintenance"
504: app server took too long to respond

500 vs. 503 for Error Handling

• 500 Internal Server Error — Unexpected errors (unhandled exceptions, bugs). These should trigger alerts.
• 503 Service Unavailable — Expected temporary unavailability (deploys, maintenance windows). These can be anticipated.

HTTP Status Codes and REST API Design

Best practices for choosing status codes in REST APIs:

Caching Behavior by Status Code

Status codes interact with HTTP caching. Not all codes are cacheable by default:

Debugging HTTP Errors

Browser DevTools

Open DevTools → Network tab → click any request to see its status code, headers, and response body. Crossed-out requests (CORS) and red rows (4xx/5xx) need attention.

Common cURL Patterns

# See status code only
curl -o /dev/null -s -w "%{http_code}" https://example.com

# See response headers
curl -I https://example.com

# Follow redirects and show each step
curl -L -v https://example.com 2>&1 | grep -E "< HTTP|Location"

# Test with a specific method
curl -X DELETE -H "Authorization: Bearer token" https://api.example.com/resource/1

Frequently Asked Questions

What’s the difference between 401 and 403? 401 means the client is not authenticated — they need to log in. 403 means the client is authenticated but doesn’t have permission. The HTTP spec’s choice to call 401 “Unauthorized” instead of “Unauthenticated” is a historical naming mistake.

When should I use 400 vs. 422? Both indicate invalid client input. 400 is typically for requests that are structurally malformed (bad JSON, wrong Content-Type). 422 is for requests that are well-formed but fail semantic validation (valid JSON, but “start date is after end date”). Many APIs use 400 for both — pick a convention and be consistent.

Is 404 or 410 better for deleted content? Use 410 Gone when you know the content existed and was permanently removed. Search engines remove 410 pages from their index faster than 404 pages. Use 404 when the URL never existed or you don’t track deletions.

Why do I see 304 responses? 304 Not Modified means the browser already has a cached copy and the server confirmed it’s still fresh. This is efficient — no response body is transferred. If you want to see the actual response during development, disable caching (DevTools → Network → Disable cache).

What causes 502 vs. 504? Both happen at a reverse proxy. A 502 means the upstream server returned an invalid or empty response (often because it crashed). A 504 means the upstream server was reachable but didn’t respond within the timeout window.

Can I use 418 in a real API? Technically yes — it’s in the IANA registry and some servers use it to signal intentional refusal (e.g., to block bots). Its use as a serious production status code is unconventional, but RFC 7168 made it an official part of the HTTP specification.