HTTP Status Codes

Client should continue the request.

When to use: Sent before a large request body to confirm the server will accept it.

Server is switching protocols per the client's request.

When to use: Used during WebSocket handshakes.

The request succeeded.

When to use: Default success response for GET, PUT, or POST that returns data.

A new resource was created.

When to use: Return after a successful POST that creates a record.

Request accepted for processing but not completed.

When to use: Use for async or queued operations.

Success with no response body.

When to use: Use for DELETE or updates that don't need to return data.

Resource permanently moved to a new URL.

When to use: Use for permanent redirects that should update bookmarks/SEO links.

Resource temporarily at a different URL.

When to use: Use for temporary redirects, e.g. after login.

Cached version is still valid.

When to use: Returned in response to conditional GET requests (ETag / If-Modified-Since).

Like 302 but preserves the HTTP method.

When to use: Use when a redirect must keep POST/PUT semantics intact.

Like 301 but preserves the HTTP method.

When to use: Permanent redirect that must not change the request method.

Malformed request syntax or invalid parameters.

When to use: Return when validation fails on the client's input.

Authentication is required or has failed.

When to use: Return when credentials are missing or invalid.

Authenticated but not permitted to access the resource.

When to use: Return when the user lacks permission, even if identity is known.

Resource does not exist.

When to use: Return for unknown routes or deleted/missing resources.

HTTP method not supported for this resource.

When to use: Return when e.g. DELETE is called on a read-only endpoint.

Request conflicts with the current state of the resource.

When to use: Use for edit conflicts, duplicate resource creation, etc.

Resource existed but was permanently removed.

When to use: Use instead of 404 when you want to signal permanent removal.

Request payload format is not supported.

When to use: Return when Content-Type doesn't match what the endpoint accepts.

Request is well-formed but semantically invalid.

When to use: Common for form/schema validation errors in APIs.

Client has sent too many requests in a given time.

When to use: Return when rate limits are exceeded, often with Retry-After.

Generic server-side failure.

When to use: Return for unexpected exceptions that aren't the client's fault.

Server doesn't support the requested functionality.

When to use: Use for unimplemented endpoints or methods.

Upstream server returned an invalid response.

When to use: Common when a reverse proxy or gateway fails to reach a backend.

Server temporarily unable to handle requests.

When to use: Use during maintenance windows or overload, often with Retry-After.

Upstream server did not respond in time.

When to use: Use when a proxy times out waiting on a backend.