HTTP Status Codes: Complete Reference

HTTP status codes are the lingua franca of web APIs. Picking the right one tells clients exactly what happened.

2xx: Success

• 200 OK — generic success with body
• 201 Created — resource created; include Location header
• 202 Accepted — async work queued; not yet done
• 204 No Content — success with empty body (DELETE, PUT updates)
• 206 Partial Content — range requests for video/large files

3xx: Redirection

• 301 Moved Permanently — caches forever; use carefully
• 302 Found — temporary redirect, but most clients change POST to GET
• 303 See Other — POST-redirect-GET pattern
• 304 Not Modified — conditional request matched ETag/If-Modified-Since
• 307 Temporary Redirect — preserves method (POST stays POST)
• 308 Permanent Redirect — like 301 but preserves method

For modern APIs use 307/308 over 302/301 to avoid method-changing surprises.

4xx: Client Errors

• 400 Bad Request — malformed request
• 401 Unauthorized — missing/invalid credentials (despite the name, this is "unauthenticated")
• 403 Forbidden — authenticated but not allowed
• 404 Not Found — resource does not exist
• 405 Method Not Allowed — endpoint exists, method doesn't (include Allow header)
• 409 Conflict — concurrent modification, duplicate resource
• 410 Gone — resource permanently removed
• 413 Payload Too Large — body bigger than limits
• 415 Unsupported Media Type — wrong Content-Type
• 422 Unprocessable Entity — syntactically valid but semantically wrong (validation errors)
• 429 Too Many Requests — rate limit hit; include Retry-After

5xx: Server Errors

• 500 Internal Server Error — catch-all, log and investigate
• 501 Not Implemented — server doesn't support the method
• 502 Bad Gateway — upstream returned invalid response
• 503 Service Unavailable — temporary overload or maintenance; include Retry-After
• 504 Gateway Timeout — upstream didn't respond in time

Common Mistakes

• Returning 200 with {"error": "..."} — clients can't react to status alone.
• Using 401 vs 403 incorrectly. 401 = "I don't know who you are." 403 = "I know who you are, you cannot do this."
• 422 vs 400: use 422 for semantic validation failures, 400 for malformed JSON or missing fields.

Real-time and Streaming

• 101 Switching Protocols — WebSocket upgrade
• 102 Processing — async hint (rare)
• 103 Early Hints — lets clients preload while server processes

103 is becoming more common with HTTP/3.

For testing endpoints see the [HTTP Status Code Lookup](https://sdk.is/http-status).