HTTP Status Code Reference
A clean, searchable reference for every HTTP status code you will meet building and consuming APIs — grouped 1xx through 5xx, each with a plain-English meaning and a note on when to use it.
1xx
InformationalThe request was received and the process is continuing.100Continue
The client should continue sending the request body; initial headers were accepted.
101Switching Protocols
The server agrees to switch protocols as requested in the Upgrade header (e.g., to WebSocket).
102Processing
WebDAV: the server has accepted the request but has not yet completed it.
103Early Hints
Used to send preliminary headers (such as preload links) before the final response.
2xx
SuccessThe request was successfully received, understood, and accepted.200OK
Standard success response. The body contains the requested resource or result.
201Created
The request succeeded and a new resource was created; the Location header should point to it.
202Accepted
The request was accepted for processing, but processing is not complete (async work).
203Non-Authoritative Information
The response is a modified version from a transforming proxy, not the origin.
204No Content
Success with no response body — common for DELETE and some PUT requests.
205Reset Content
Success; the client should reset the document view (e.g., clear a form).
206Partial Content
The server is delivering part of the resource in response to a Range header.
3xx
RedirectionFurther action is needed to complete the request.301Moved Permanently
The resource has a new permanent URL; update links. Search engines transfer ranking.
302Found
Temporary redirect. The method may change on redirect in practice — prefer 307 to preserve it.
303See Other
Redirects to another URL with a GET request, typically after a POST (POST/redirect/GET).
304Not Modified
The cached copy is still valid; used with conditional requests (If-None-Match / ETag).
307Temporary Redirect
Like 302 but guarantees the HTTP method and body are not changed on the redirect.
308Permanent Redirect
Like 301 but guarantees the method and body are preserved on the redirect.
4xx
Client ErrorThe request contains bad syntax or cannot be fulfilled.400Bad Request
The server cannot process the request due to a client error (malformed syntax, invalid body).
401Unauthorized
Authentication is required or has failed. Despite the name, it means 'unauthenticated'.
402Payment Required
Reserved for future use; some APIs use it to signal a billing or quota issue.
403Forbidden
The client is authenticated but not allowed to access this resource. Authorization failed.
404Not Found
The requested resource does not exist, or the server hides its existence.
405Method Not Allowed
The HTTP method is not supported for this resource (e.g., POST to a read-only endpoint).
406Not Acceptable
The resource cannot be returned in a form matching the request's Accept headers.
408Request Timeout
The server timed out waiting for the client to finish sending the request.
409Conflict
The request conflicts with the current state (e.g., a duplicate or version mismatch).
410Gone
The resource was intentionally removed and will not return. Stronger than 404.
415Unsupported Media Type
The request body's Content-Type is not supported by the endpoint.
418I'm a Teapot
An April Fools' joke from RFC 2324. Returned by some servers as an easter egg.
422Unprocessable Content
The syntax is valid but the request is semantically wrong — common for validation errors.
429Too Many Requests
The client has sent too many requests in a window. Honor the Retry-After header.
5xx
Server ErrorThe server failed to fulfill a valid request.500Internal Server Error
A generic catch-all for an unexpected condition on the server. Check your logs.
501Not Implemented
The server does not support the functionality required to fulfill the request.
502Bad Gateway
A gateway or proxy received an invalid response from an upstream server.
503Service Unavailable
The server is temporarily overloaded or down for maintenance. Often paired with Retry-After.
504Gateway Timeout
A gateway or proxy did not get a timely response from an upstream server.
505HTTP Version Not Supported
The server does not support the HTTP protocol version used in the request.
Reading status codes like a protocol designer
HTTP status codes are organized by their first digit, and that first digit tells you almost everything you need at a glance. 1xx is informational — rarely seen directly. 2xx means success. 3xx means redirection — go look elsewhere. 4xx means the client made a mistake. 5xx means the server did. Internalizing this five-bucket model turns an opaque number into a clear signal the moment it lands in your logs.
The codes people get wrong are almost always in the 4xx range. The 401-versus-403 confusion is endemic: 401 means "I do not know who you are" (authenticate), while 403 means "I know who you are and you still cannot have this" (authorization failed). Returning 404 instead of 403 is sometimes a deliberate security choice — hiding the existence of a resource from users who should not know it is there. And 422 has quietly become the convention for field-level validation errors, leaving 400 for requests the server cannot even parse.
Status codes are an API contract. Clients make retry, caching, and error-handling decisions based on them. A 429 should trigger back-off, not an immediate retry. A 503 with a Retry-After is a polite "come back soon"; a 500 usually is not worth retrying without a fix. A 304 lets a client reuse its cache and skip a download entirely. Choosing the right code is not pedantry — it is how you let well-behaved clients do the right thing automatically. We design exactly these contracts in our API development work and our SaaS platform builds.
If the underlying concepts are new, our glossary entries on what an API is and what webhooks are give you the foundation — status codes make a lot more sense once you see how requests and responses flow.
How to use it
Type a number like 404 or a keyword like redirect, unauthorized, or rate limit into the search box. The list filters instantly across codes, names, and descriptions, keeping the class groupings intact so you keep your bearings. Hover any card to reveal a copy button that grabs the code and its name. The whole reference is static data filtered locally — searching makes no network requests.
FAQs
What is the difference between 401 and 403?
401 Unauthorized actually means unauthenticated — the server does not know who you are, so you need to log in or supply valid credentials. 403 Forbidden means the server knows who you are but you are not allowed to access this resource; authenticating again will not help. A useful rule of thumb: 401 says 'who are you?', 403 says 'I know who you are, and no.' Returning the right one matters for both correct client behavior and security.
When should an API return 400 versus 422?
Use 400 Bad Request when the request itself is malformed — invalid JSON, a missing required header, a body the server cannot even parse. Use 422 Unprocessable Content when the syntax is valid but the data fails business or validation rules, such as an email that is well-formed but already taken, or a date in the past where a future one is required. Many teams standardize on 422 for field-level validation errors and reserve 400 for structurally broken requests.
Which redirect should I use — 301, 302, 307, or 308?
Use 301 Moved Permanently when a URL has changed for good; browsers and search engines cache it and transfer ranking. Use 302 Found or 303 See Other for temporary redirects. The catch with 301 and 302 is that clients historically changed the method (turning a POST into a GET) on redirect. If you must preserve the original method and body, use 308 (permanent) or 307 (temporary), which guarantee the method does not change.
What does a 429 Too Many Requests response require of the client?
429 signals that the client has exceeded a rate limit. A well-behaved client must back off rather than retry immediately — and the server should include a Retry-After header telling it how long to wait. Hammering an endpoint that returns 429 will only extend the lockout. On the server side, returning 429 with a clear Retry-After (and ideally rate-limit headers showing the remaining quota) is far friendlier than silently dropping requests.
Is this reference complete and where does the data come from?
It covers the status codes you will actually encounter building and consuming web APIs, grouped by class with plain-English summaries and guidance on when each applies. The codes and their official meanings are defined by the IANA HTTP Status Code Registry and the relevant RFCs. The reference loads as static data and filters entirely in your browser — there are no network requests when you search.
Related tools
Related engineering reading
All postsAdding AI Features to Your SaaS (2026)
Where AI helps, build-vs-API trade-offs, evals, guardrails, and shipping without torching margins.
Read postAPI Rate Limiting Strategies for 2026
Token bucket vs sliding window, per-key quotas, 429 semantics, and where to enforce limits.
Read postAPI Security Best Practices (2026)
Auth, rate limiting, input validation, secrets, and the OWASP API Top 10.
Read post
APIs that return the right code, every time
Consistent status codes, predictable error shapes, and sane retry semantics are what separate an API that integrators love from one they dread. We design and build them — and clean up the ones that return 200 on failure. Talk to us about your API or platform.
Or reach us directly: (770) 652-1282 · beltz@quantlabusa.dev