Adamant Solutions

HTTP status codes for API designers

What each code means and the mistake teams make most often with it. Definitions follow RFC 9110 and related RFCs. Search by number or word (for example 429 or rate limit). We only count anonymous visits (no cookies, no IP).

100 Continue

The server received the request headers; the client may send the body (used with Expect: 100-continue).

Common mistake: Rarely handled by hand: HTTP libraries do it. Do not return it from application code.

101 Switching Protocols

The server agrees to change protocol, for example to WebSocket after an Upgrade request.

Common mistake: Not a response to normal API calls.

200 OK

The request succeeded and the response carries a body (GET result, update that returns the resource).

Common mistake: Returning 200 with an error message in the body hides failures from clients, caches and monitoring.

201 Created

A new resource was created. Send a Location header with its URL and, usually, the resource in the body.

Common mistake: Using 200 for creation, or omitting Location.

202 Accepted

The request was accepted for processing that is not finished (asynchronous work). Give a status URL or job id.

Common mistake: Returning 202 and never offering a way to learn the outcome.

204 No Content

Success with no body: typical for DELETE and for PUT/PATCH that return nothing.

Common mistake: Sending a body with 204 (it must be empty).

206 Partial Content

A range request succeeded (Range header): used for resumable downloads and media.

Common mistake: Ignoring Range and always sending the full file.

301 Moved Permanently

The resource has a new permanent URL. Clients and search engines should update links.

Common mistake: Using it for temporary moves: browsers cache it. POST may be changed to GET; use 308 to keep the method.

302 Found

Temporary redirect (historically ambiguous about the method).

Common mistake: Prefer 303 or 307 to be explicit about the method.

303 See Other

After a POST, redirect the client to GET another resource (for example the result).

Common mistake: Using 302 and relying on client-specific behaviour.

304 Not Modified

Conditional GET (If-None-Match / If-Modified-Since): the cached copy is still valid; no body.

Common mistake: Sending 200 with the full body when an ETag matches, wasting bandwidth.

307 Temporary Redirect

Temporary redirect that keeps the method and body (a POST stays a POST).

Common mistake: Confusing it with 302.

308 Permanent Redirect

Permanent redirect that keeps the method and body.

Common mistake: Using 301 for APIs where POST must stay POST.

400 Bad Request

The request is malformed or fails basic validation (bad JSON, wrong types, missing required field).

Common mistake: Using it for everything. Prefer 401, 403, 404, 409 or 422 when they describe the problem better.

401 Unauthorized

Authentication is missing or invalid (no or bad credentials/token). Send a WWW-Authenticate header.

Common mistake: Using it when the user is known but not allowed: that is 403.

402 Payment Required

Reserved for future use; some APIs use it for exhausted quotas or unpaid plans.

Common mistake: Relying on a standard meaning: there is none.

403 Forbidden

The server understood the request and the identity, but refuses: the caller lacks permission.

Common mistake: Returning 403 instead of 404 can reveal that a resource exists; choose deliberately.

404 Not Found

No resource at this URL (or the server will not reveal that it exists).

Common mistake: Using it for an empty list: a collection with no items is 200 with [].

405 Method Not Allowed

The URL exists but not for this method. Send an Allow header listing the valid ones.

Common mistake: Returning 404 for a wrong method.

406 Not Acceptable

The server cannot produce any representation the Accept header allows.

Common mistake: Ignoring Accept silently.

408 Request Timeout

The server gave up waiting for the client to finish sending the request.

Common mistake: Using it when your own backend is slow: that is 504 or 503.

409 Conflict

The request conflicts with the current state: duplicate unique value, version mismatch, edit of a locked item.

Common mistake: Using 400 for conflicts, so clients cannot tell what to fix.

410 Gone

The resource existed and was permanently removed, with no forwarding address.

Common mistake: Using 404 for a deliberate, permanent removal that clients should stop requesting.

412 Precondition Failed

A condition such as If-Match failed: the resource changed since the client read it (optimistic locking).

Common mistake: Not supporting If-Match, which leads to lost updates.

413 Content Too Large

The request body is larger than the server accepts.

Common mistake: Closing the connection without a response.

415 Unsupported Media Type

The Content-Type of the body is not supported (for example XML sent to a JSON-only endpoint).

Common mistake: Returning 400 without saying which type is expected.

418 I'm a teapot

Defined in an April Fools RFC (2324); not a real API code.

Common mistake: Using it for real errors.

422 Unprocessable Content

The JSON is well-formed but its content is semantically invalid (a business rule or validation rule failed).

Common mistake: Mixing 400 and 422 inconsistently: pick one convention for validation and document it.

423 Locked

The resource is locked (WebDAV, RFC 4918).

Common mistake: Using it outside lock semantics.

425 Too Early

The server will not process a request that might be replayed (TLS early data).

Common mistake: Rarely needed by application APIs.

428 Precondition Required

The server requires a conditional request (for example If-Match) to avoid lost updates (RFC 6585).

Common mistake: Allowing blind overwrites.

429 Too Many Requests

Rate limit exceeded (RFC 6585). Send Retry-After and, ideally, limit headers.

Common mistake: Using 503 for rate limits, or not telling the client when to retry.

431 Request Header Fields Too Large

Headers (often cookies or tokens) are too big (RFC 6585).

Common mistake: Putting large data in headers.

451 Unavailable For Legal Reasons

Access is denied for a legal reason (RFC 7725).

Common mistake: Using 403 and hiding the legal cause.

500 Internal Server Error

An unexpected server fault. Log it and return a generic body with a correlation id.

Common mistake: Using it for client mistakes, or exposing stack traces.

501 Not Implemented

The server does not support the requested method or feature at all.

Common mistake: Using it for a feature that is only temporarily off: use 503.

502 Bad Gateway

A gateway or proxy got an invalid response from the upstream server.

Common mistake: Blaming the client: look at the upstream service.

503 Service Unavailable

The server is temporarily unable to handle requests (maintenance, overload). Send Retry-After.

Common mistake: Returning 500 for planned maintenance.

504 Gateway Timeout

A gateway or proxy did not get a timely response from the upstream server.

Common mistake: Setting timeouts so that clients give up before the gateway does.

How to use this tool

  1. Search by number or word, or filter by class (2xx, 3xx, 4xx, 5xx).
  2. Open a code to read its meaning and the most common mistake.
  3. Use the link next to a code to share it.

Example

Searching 429 shows when to return Too Many Requests and that Retry-After should accompany it. Searching 401 next to 403 shows the difference between "who are you?" and "you may not".

Limits

A reference for API designers, not the full registry. Definitions follow RFC 9110 and related RFCs; check them for edge cases.

Privacy and security of what you enter

This page collects nothing about what you search; we only count anonymous visits. See the privacy notice.

Designing or fixing an API?

We review API contracts, error handling, authentication and rate limits. See the security review, or check a spec with the free agent-readiness check.

Message us on LinkedIn

Privacy and cookies