bigonotes
System DesignAPI Design

HTTP Status Codes

The HTTP status codes you'll actually use in API design, grouped by class, with what triggers each.

2 min readLast updated API Design
On this page4 sections

Every HTTP response starts with a three-digit status code that tells the client what happened before it reads the body. The first digit gives the class: 2xx success, 3xx redirection, 4xx the client made a mistake, 5xx the server failed. You don't need to memorize them all; the ones below cover nearly every API you'll design.

The codes that matter#

These are the codes you will reach for most, grouped by class.

Code Name Typical trigger
2xx Success
200 OK Successful page load or API fetch
201 Created A new resource was created, usually after a POST
204 No Content Success with nothing to return, e.g. a DELETE
3xx Redirection
301 Moved Permanently The URL changed for good; clients and search engines should use the new one
302 Found (temporary redirect) Go to another URL for now, but keep using the original
304 Not Modified The client's cached copy is still valid, which saves bandwidth
4xx Client error
400 Bad Request Malformed data or invalid syntax from the client
401 Unauthorized Authentication is missing or invalid
403 Forbidden The server knows who you are, but you don't have permission
404 Not Found No resource at this URL
429 Too Many Requests A rate limit was hit
5xx Server error
500 Internal Server Error Generic catch-all for an unexpected server failure
502 Bad Gateway A proxy or gateway got an invalid response from an upstream server
503 Service Unavailable Overloaded or down for maintenance
504 Gateway Timeout A proxy or gateway gave up waiting for a slow upstream

Distinctions that come up often#

Three pairs of codes are easy to mix up.

  • 401 vs 403: 401 means "we don't know who you are, so log in". 403 means "we know who you are, and the answer is no".
  • 301 vs 302: browsers may cache a 301 and skip your server next time. A URL shortener that wants to count every click usually returns 302 so each visit still reaches it.
  • 4xx vs 5xx: 4xx means the client should fix the request, and retrying unchanged won't help (429 is the exception: retry later). 5xx means the server failed, and a retry may succeed.

Key takeaways#

  • The first digit tells you who's responsible: 2xx fine, 3xx go elsewhere, 4xx client's fault, 5xx server's fault.
  • Use 201 for creates, 204 for empty successes, and 429 for rate limits.
  • Know 401 vs 403 and 301 vs 302. Both come up in design discussions.

Found a mistake? Tell me on LinkedIn ↗

Further reading#