🔢Developer
HTTP Status Codes: The Ones That Actually Matter
Not a reference list — a practical guide to the status codes you'll encounter as a developer or website owner, what they mean, and what to do about them.
Free to read
Advertisement
The full HTTP status code spec runs to 70+ codes. Most developers work with maybe 15 regularly. Here are the ones worth actually understanding.
The 2xx Success Codes
- 200 OK: Standard success. The request worked.
- 201 Created: A new resource was created (after a POST). The response should include the new resource or a Location header pointing to it.
- 204 No Content: Success but nothing to return. Correct for DELETE operations and some PUT operations. The client should not expect a response body.
- 206 Partial Content: Used with range requests. Streaming video uses this — the server sends part of the file in response to a range header.
The 3xx Redirects
- 301 Moved Permanently: URL changed forever. Browsers and search engines update their records. Use for permanent URL changes.
- 302 Found (temporary redirect): Go here for now, but check back at the original URL later. Use sparingly.
- 304 Not Modified: Response to a conditional GET when the cached version is still valid. The browser uses its cached copy.
- 307 Temporary Redirect: Like 302 but explicitly preserves the HTTP method (POST stays POST, not converted to GET).
- 308 Permanent Redirect: Like 301 but preserves method. Useful when moving POST endpoints permanently.
The 4xx Client Errors
- 400 Bad Request: Malformed request — usually invalid JSON, missing required fields, or wrong content type. The client sent something the server can't parse.
- 401 Unauthorized: Authentication required or failed. Despite the name, it's actually about authentication (who are you?), not authorization (can you?). Include a WWW-Authenticate header.
- 403 Forbidden: Authenticated but not permitted. You know who they are; they're not allowed. No amount of re-authenticating will help.
- 404 Not Found: Resource doesn't exist. Also used when you want to hide the existence of a resource from unauthorized users (instead of 403).
- 405 Method Not Allowed: The resource exists but doesn't support this HTTP method. DELETE on a read-only endpoint.
- 409 Conflict: Request conflicts with current state — duplicate unique field, optimistic locking failure.
- 422 Unprocessable Entity: Syntactically valid but semantically wrong. Often used for validation errors in REST APIs.
- 429 Too Many Requests: Rate limit exceeded. Include Retry-After header.
The 5xx Server Errors
- 500 Internal Server Error: Something broke on the server. Check logs immediately.
- 502 Bad Gateway: The server received an invalid response from an upstream server. Common with reverse proxies and load balancers when the application server is down.
- 503 Service Unavailable: Server temporarily unable to handle requests — overloaded or down for maintenance. Include Retry-After header.
- 504 Gateway Timeout: Upstream server didn't respond in time. Common cause: database queries taking too long, external API calls timing out.
API design note
Use 400 for any malformed or invalid client request. Use 422 specifically for validation failures (field-level errors with detail). Use 500 only for genuine server bugs. Clients need to handle these differently: 400s require client code changes; 500s warrant a retry or escalation.
Frequently Asked Questions
What's the difference between a 301 and 302 redirect?+
301 is a permanent redirect — tells browsers and search engines to update their records and use the new URL going forward. Link equity (SEO value) transfers with a 301. 302 is a temporary redirect — tells clients to use the new URL for now but the original is still the canonical. Search engines generally won't transfer link equity for a 302. Always use 301 for permanent URL changes (a page renamed, old domain to new domain), and 302 for genuinely temporary situations (a page under maintenance, A/B testing).
What causes a 500 Internal Server Error?+
Almost anything can cause a 500 — it's the catch-all for server-side errors. Common causes: an unhandled exception in your application code, a database connection failure, a misconfigured environment variable, a PHP/Python/Node syntax error, a timeout on an external API call, or running out of memory. Check your server error logs immediately — the 500 response tells the client nothing useful, but the logs should have the specific error. '500' from the user's perspective means 'something broke on our end.'
Why does my API return 200 with error data instead of an error status code?+
This is an anti-pattern called '200 OK with error body' — unfortunately very common in older APIs and some payment gateways. It breaks HTTP semantics: clients have to parse the response body to determine success/failure rather than checking the status code. If you control the API, use appropriate error codes (400 for client errors, 500 for server errors). If you're consuming an API that does this, you need custom error parsing logic.
What does 429 Too Many Requests mean?+
The server is rate-limiting your requests. You've sent too many in a defined time window. The response should include a Retry-After header indicating when you can try again. Best practice in client code: implement exponential backoff — wait, then retry, and double the wait time on each subsequent rate limit hit. Don't immediately retry in a tight loop, which will make the problem worse.
Advertisement
🔧 Free Tools Used in This Guide
PS
Priya Shah
Senior Software Engineer · 9+ years experience
Priya has nine years of experience building distributed systems and developer tooling at two B2B SaaS companies. She writes about APIs, JSON/JWT workflows, regex, DevOps, and the small utilities that make debugging faster at 2am.
View all posts by Priya Shah →Tags:
httpdeveloperstatus-codesweb