Reference for API Documentation

Used for requests with Expect: 100-continue. The server acknowledges that it's willing to receive the body before the client sends it. Rarely seen in modern web apps.

Most commonly used for WebSocket upgrades — the client requests Upgrade: websocket and the server responds 101 to switch.

The standard success response. The meaning depends on the HTTP method: GET → resource returned, POST/PUT → action completed.

Common after a POST. The response should include a Location header pointing to the new resource's URL.

For async operations — the server is queuing the work. The client should poll a status endpoint or check back later.

Often used for DELETE operations or PUT updates that don't need to return a body. The client should not navigate away from the current page.

Response to a Range request. Used by video players and download managers to resume interrupted downloads or stream large files.

Use for permanent URL changes — search engines will update their index. SEO authority transfers to the new URL.

Indicates the redirect is not permanent. Caching is less aggressive than 301. Use for things like "login required, redirecting to /login".

Used after POST submissions — the response says "your POST worked, see this GET URL for the result". Browsers always GET the new URL.

Response to a conditional request (with If-None-Match or If-Modified-Since headers). Saves bandwidth — no body is returned.

If the original was POST, the redirect also uses POST. Modern alternative to 302 when method preservation matters.

Modern replacement for 301 when you want POST requests to remain POST after the redirect.

Common causes: malformed JSON in body, invalid query parameters, or missing required fields. Check the request body and headers.

The client must include authentication credentials (Authorization header, cookie, token). "Unauthorized" is a misnomer — it really means "unauthenticated".

Originally intended for digital payments. Modern usage: APIs sometimes return 402 when a user has exceeded their paid quota.

Different from 401 — the user IS logged in, but their account doesn't have permission for this resource. Check role/permissions logic.

Either the URL is wrong, the resource was deleted, or it never existed. Servers sometimes return 404 to hide that a 403 would be more accurate.

For example, a GET request to an endpoint that only accepts POST. The response should include an Allow header listing valid methods.

The client took too long to send the request body or kept the connection idle. Try the request again.

Typically returned for concurrent edit conflicts or duplicate resource creation (e.g., creating a user with an email that already exists).

Stronger than 404 — the server explicitly knows the resource USED to exist but has been permanently removed. Search engines will deindex.

Common when uploading large files. Server config (nginx, apache) sets a max body size. Check the server's configuration.

For example, sending application/xml to a server that only accepts application/json. Set the Content-Type header correctly.

An April Fool's joke from 1998 (RFC 2324). Some real APIs use it for jokes or to mark deprecated endpoints. Not for production use.

For example, JSON parsed correctly but a required field was missing, or a field value was out of range. Common in REST API validation responses.

Slow down. The response should include a Retry-After header indicating when to try again. Common with APIs that have request quotas.

A generic catch-all for server-side errors. Check server logs for the actual cause: unhandled exception, database error, etc.

For example, the server doesn't recognize the HTTP method. Rare in practice — more often you'll see 405.

Common in microservice architectures. Your load balancer or reverse proxy got a malformed response from the backend service.

Either down for maintenance or overloaded. The response should include a Retry-After header. Often returned during deployments.

The backend service didn't respond fast enough. Check upstream service health and timeout configurations.

WebDAV-specific in origin but sometimes used by general servers. Means the server can't save the request because of storage constraints.

Used by captive portals (hotel/airport WiFi) to indicate the user must log in to the network before accessing external sites.