HTTP Status Codes

Status code categories at a glance

• 1xx Informational — request received, processing continues. Rare in practice.
• 2xx Success — request succeeded.
• 3xx Redirection — further action needed to complete.
• 4xx Client errors — client's fault (bad syntax, bad auth, bad resource).
• 5xx Server errors — server's fault (broken, overloaded, misconfigured).

Common status-code debates

401 vs 403

401 Unauthorized — "I don't know who you are." The request has no credentials, or the credentials are invalid/expired. Reply to an unauthenticated client.

403 Forbidden — "I know who you are and you can't have this." Credentials are valid but the user lacks permission for the resource.

The 401 name is a misnomer — it really means unauthenticated, not unauthorized. Too late to rename now.

422 vs 400

400 Bad Request — the request itself is malformed (invalid JSON, missing required headers, bad syntax).

422 Unprocessable Entity — the request is syntactically valid but semantically wrong (email address is well-formed but not a real email, user ID exists but isn't active). Most modern APIs prefer 422 for business-rule validation failures.

301 vs 302 vs 307 vs 308

• 301 Moved Permanently — permanent, but some clients change the request method from POST to GET (historical bug that became de facto behavior).
• 302 Found — temporary, same method-change issue.
• 307 Temporary Redirect — like 302 but preserves the HTTP method. Safe for POST.
• 308 Permanent Redirect — like 301 but preserves the method. Prefer 308 for modern APIs.

204 No Content

204 returns success with no body. Use it for PUT/DELETE success, or for any endpoint where the client doesn't need a response payload. Pairs with Content-Length: 0. Saves bytes on high-volume endpoints.

429 Too Many Requests

Rate-limit hit. Always include Retry-After (seconds or HTTP-date) so clients know when to retry. Good APIs also include X-RateLimit-Remaining and X-RateLimit-Reset.

Tips for choosing the right status

• Use 201 after creating a resource, and include a Location header pointing to the new resource.
• Use 202 for long-running async tasks — return a polling URL.
• Use 503 for planned downtime with Retry-After.
• Never use 200 for errors. Returning a JSON body like {"success": false, "error": "..."} with a 200 status is a common bug — clients check status codes, not bodies.
• Don't over-engineer. 200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500 cover 95% of real APIs.

Related tools

• JSON Formatter — Format, validate, and beautify JSON online. 100% client-side — your data never leaves your browser.
• URL Encoder / Decoder — Percent-encode and decode URLs per RFC 3986.
• JWT Decoder — Decode and inspect JSON Web Tokens. Local-only — tokens never leave your browser.
• Regex Tester — Test regular expressions with live match highlighting and explanation.

Pillar

Part of Dev Productivity — regex, cron, timestamps, HTTP, color, word counter, aspect ratio, case.

Written by Mian Ali Khalid. Last updated 2026-04-25.