HTTP Status Codes: The Only Reference Guide Developers Need

Why HTTP Status Codes Matter

Every HTTP response includes a three-digit status code. It tells the client what happened with their request. Using the right status code makes your API predictable, debuggable, and standards-compliant.

Using the wrong status code — like returning 200 OK with an error in the body — breaks client-side error handling, confuses monitoring tools, and makes debugging painful.

The Five Categories

• 1xx Informational — request received, continuing
• 2xx Success — request was successful
• 3xx Redirection — further action needed
• 4xx Client Error — problem with the request
• 5xx Server Error — problem with the server

The Status Codes You'll Use 95% of the Time

Success

• 200 OK — the standard success response
• 201 Created — resource was created (use after POST)
• 204 No Content — success but nothing to return (use after DELETE)

Redirection

• 301 Moved Permanently — use for URL changes (SEO-friendly)
• 302 Found — temporary redirect
• 304 Not Modified — use cached version (saves bandwidth)

Client Errors

• 400 Bad Request — malformed request body or parameters
• 401 Unauthorized — no valid authentication credentials
• 403 Forbidden — authenticated but not authorized
• 404 Not Found — resource doesn't exist
• 409 Conflict — request conflicts with current state
• 422 Unprocessable Entity — valid syntax but semantic errors
• 429 Too Many Requests — rate limited

Server Errors

• 500 Internal Server Error — generic server failure
• 502 Bad Gateway — upstream server returned invalid response
• 503 Service Unavailable — server temporarily overloaded
• 504 Gateway Timeout — upstream server didn't respond in time

The Confusing Pairs

401 vs 403

• 401: "I don't know who you are" → provide credentials
• 403: "I know who you are, but you can't do this" → get better permissions

502 vs 504

• 502: Upstream server responded but the response was invalid
• 504: Upstream server didn't respond at all (timeout)

400 vs 422

• 400: Request is malformed (can't parse the JSON)
• 422: Request is well-formed but semantically wrong (email field is not a valid email)

Quick Reference

Bookmark our [HTTP status code reference](/tools/http-status-codes) — a searchable, filterable table of all status codes with descriptions and debugging tips.

Status Codes in Error Monitoring

A spike in 500 errors means your server is broken. A spike in 429 errors means you're being rate-limited. A spike in 401 errors might mean your auth token rotation is failing.

Bugsly tracks HTTP status codes across all your endpoints and alerts you when error rates spike. No more guessing if the 502 errors are increasing — the dashboard tells you. [Get started free](/signup).