Web & marketing

HTTP Status Code Reference

Search and learn the meaning, typical cause and use case of every common HTTP status code, with cURL/Python/JS/PHP snippets.

100 Continue #

An interim response that signals the server has received the request headers and the client should proceed to send the request body. Defined in RFC 9110 section 15.2.1.

Common cause

The client sent an Expect: 100-continue header to test whether the server will accept a large body before transmitting it.

When to use it

Used between the headers and the body of long uploads (PUT, POST) so the client doesn’t waste bandwidth on a request the server would reject.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 100 Continue

import requests
r = requests.get("https://example.com/path")
if r.status_code == 100:
    print("Continue")

const r = await fetch("https://example.com/path");
if (r.status === 100) {
  console.log("Continue");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 100);
// or:
http_response_code(100);

101 Switching Protocols #

The server agrees to switch to a different application protocol on the same TCP connection, listed in the Upgrade header. RFC 9110 §15.2.2.

Common cause

The client requested an Upgrade (typically to WebSocket or HTTP/2 over h2c) and the server accepted it.

When to use it

WebSocket handshakes are the dominant case today. After 101 the connection is no longer HTTP.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 101 Switching Protocols

import requests
r = requests.get("https://example.com/path")
if r.status_code == 101:
    print("Switching Protocols")

const r = await fetch("https://example.com/path");
if (r.status === 101) {
  console.log("Switching Protocols");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 101);
// or:
http_response_code(101);

200 OK #

Standard success response — the request succeeded and the response body carries the requested representation. RFC 9110 §15.3.1.

Common cause

The request was valid, authorised and satisfied without redirection.

When to use it

GETs that return data, POSTs/PUTs that processed inline rather than asynchronously, healthy API responses.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 200 OK

import requests
r = requests.get("https://example.com/path")
if r.status_code == 200:
    print("OK")

const r = await fetch("https://example.com/path");
if (r.status === 200) {
  console.log("OK");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 200);
// or:
http_response_code(200);

201 Created #

The request succeeded and a new resource was created as a direct result. The Location header SHOULD point to the new resource. RFC 9110 §15.3.2.

Common cause

A POST or PUT created a resource (a database row, a file, a user, etc.).

When to use it

Use after creating REST resources. Return the new representation in the body and a Location header.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 201 Created

import requests
r = requests.get("https://example.com/path")
if r.status_code == 201:
    print("Created")

const r = await fetch("https://example.com/path");
if (r.status === 201) {
  console.log("Created");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 201);
// or:
http_response_code(201);

202 Accepted #

The request has been accepted for processing but is not yet complete. The processing may eventually succeed or fail. RFC 9110 §15.3.3.

Common cause

Asynchronous processing has been queued. The work happens later.

When to use it

Background jobs, batch import endpoints, anything that returns a job-status URL while the work is still running.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 202 Accepted

import requests
r = requests.get("https://example.com/path")
if r.status_code == 202:
    print("Accepted")

const r = await fetch("https://example.com/path");
if (r.status === 202) {
  console.log("Accepted");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 202);
// or:
http_response_code(202);

204 No Content #

The request succeeded; the response intentionally has no body. Headers may carry metadata. RFC 9110 §15.3.5.

Common cause

An update or delete that doesn’t need to return a representation.

When to use it

DELETE responses, PUT/PATCH where the client already has the new representation, save-and-stay endpoints.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 204 No Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 204:
    print("No Content")

const r = await fetch("https://example.com/path");
if (r.status === 204) {
  console.log("No Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 204);
// or:
http_response_code(204);

206 Partial Content #

The server returned only part of the representation in response to a Range request. RFC 9110 §15.3.7.

Common cause

The client asked for a byte range using the Range header.

When to use it

Resumable downloads, video streaming with seek, and parallel chunk downloads.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 206 Partial Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 206:
    print("Partial Content")

const r = await fetch("https://example.com/path");
if (r.status === 206) {
  console.log("Partial Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 206);
// or:
http_response_code(206);

301 Moved Permanently #

The target resource has a new permanent URI. Clients SHOULD update bookmarks and search engines update their indexes. RFC 9110 §15.4.2.

Common cause

A canonical URL change — domain rename, slug fix, HTTPS migration.

When to use it

Long-term redirects. Avoid 301 for short-lived redirects because clients and intermediaries cache aggressively.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 301 Moved Permanently

import requests
r = requests.get("https://example.com/path")
if r.status_code == 301:
    print("Moved Permanently")

const r = await fetch("https://example.com/path");
if (r.status === 301) {
  console.log("Moved Permanently");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 301);
// or:
http_response_code(301);

302 Found #

The target resource resides temporarily under a different URI. Clients should request the new URI without changing the method semantics, but historically most rewrite POST to GET. RFC 9110 §15.4.3.

Common cause

Temporary redirect with quirky method-rewrite behaviour, retained for legacy compatibility.

When to use it

Legacy code paths. Prefer 303 or 307 in new APIs to be unambiguous about method handling.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 302 Found

import requests
r = requests.get("https://example.com/path")
if r.status_code == 302:
    print("Found")

const r = await fetch("https://example.com/path");
if (r.status === 302) {
  console.log("Found");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 302);
// or:
http_response_code(302);

303 See Other #

Redirects to a resource that should be retrieved with GET, regardless of the original method. RFC 9110 §15.4.4.

Common cause

After a non-idempotent POST, the server sends the client to a confirmation page or a freshly-created resource.

When to use it

Post/Redirect/Get pattern. Always rewrites to GET, so safe after a form submission.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 303 See Other

import requests
r = requests.get("https://example.com/path")
if r.status_code == 303:
    print("See Other")

const r = await fetch("https://example.com/path");
if (r.status === 303) {
  console.log("See Other");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 303);
// or:
http_response_code(303);

304 Not Modified #

The cached representation the client already holds is still valid; no body is sent. RFC 9110 §15.4.5.

Common cause

The client sent If-None-Match or If-Modified-Since and the validators matched the current resource.

When to use it

Conditional GET responses for caching. Saves bandwidth on unchanged static assets and API replies.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 304 Not Modified

import requests
r = requests.get("https://example.com/path")
if r.status_code == 304:
    print("Not Modified")

const r = await fetch("https://example.com/path");
if (r.status === 304) {
  console.log("Not Modified");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 304);
// or:
http_response_code(304);

307 Temporary Redirect #

Like 302 but explicitly preserves the request method and body. RFC 9110 §15.4.8.

Common cause

A short-term redirect where the original POST/PUT must be replayed at the new URI.

When to use it

Maintenance redirects, A/B routing or geo redirects that must keep the original method.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 307 Temporary Redirect

import requests
r = requests.get("https://example.com/path")
if r.status_code == 307:
    print("Temporary Redirect")

const r = await fetch("https://example.com/path");
if (r.status === 307) {
  console.log("Temporary Redirect");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 307);
// or:
http_response_code(307);

308 Permanent Redirect #

Like 301 but explicitly preserves the request method and body. RFC 9110 §15.4.9.

Common cause

A canonical URI change for non-GET methods (HTTPS upgrade for POST APIs, route renames).

When to use it

REST API permanent redirects. Use instead of 301 when the original method must not be rewritten.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 308 Permanent Redirect

import requests
r = requests.get("https://example.com/path")
if r.status_code == 308:
    print("Permanent Redirect")

const r = await fetch("https://example.com/path");
if (r.status === 308) {
  console.log("Permanent Redirect");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 308);
// or:
http_response_code(308);

400 Bad Request #

The server cannot process the request due to a client error: malformed syntax, invalid framing, deceptive routing. RFC 9110 §15.5.1.

Common cause

Broken JSON, missing required field, malformed header, oversized cookie.

When to use it

Generic client error fallback. Prefer more specific codes (422, 411, 415) when they apply.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 400 Bad Request

import requests
r = requests.get("https://example.com/path")
if r.status_code == 400:
    print("Bad Request")

const r = await fetch("https://example.com/path");
if (r.status === 400) {
  console.log("Bad Request");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 400);
// or:
http_response_code(400);

401 Unauthorized #

The request lacks valid authentication credentials. The response MUST include a WWW-Authenticate header listing accepted schemes. RFC 9110 §15.5.2.

Common cause

Missing, expired or invalid token; no Authorization header where one is required.

When to use it

API endpoints behind authentication. Distinct from 403 — 401 is "not authenticated", 403 is "authenticated but not allowed".

curl -i -X HEAD https://example.com/path
# HTTP/1.1 401 Unauthorized

import requests
r = requests.get("https://example.com/path")
if r.status_code == 401:
    print("Unauthorized")

const r = await fetch("https://example.com/path");
if (r.status === 401) {
  console.log("Unauthorized");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 401);
// or:
http_response_code(401);

403 Forbidden #

The server understood the request but refuses to authorise it. RFC 9110 §15.5.4.

Common cause

The user is authenticated but lacks permission, or the resource is blocked from the user’s IP / region.

When to use it

Authorization failures, IP allowlists, role-based access controls.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 403 Forbidden

import requests
r = requests.get("https://example.com/path")
if r.status_code == 403:
    print("Forbidden")

const r = await fetch("https://example.com/path");
if (r.status === 403) {
  console.log("Forbidden");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 403);
// or:
http_response_code(403);

404 Not Found #

The server can’t find a current representation of the target resource. May also be used to hide a 403. RFC 9110 §15.5.5.

Common cause

URL typo, deleted resource, or resource that never existed.

When to use it

Default response for missing routes and resources. Caches less aggressively than 410.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 404 Not Found

import requests
r = requests.get("https://example.com/path")
if r.status_code == 404:
    print("Not Found")

const r = await fetch("https://example.com/path");
if (r.status === 404) {
  console.log("Not Found");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 404);
// or:
http_response_code(404);

405 Method Not Allowed #

The method is not supported on the resource. The response MUST include an Allow header listing supported methods. RFC 9110 §15.5.6.

Common cause

Calling DELETE on a read-only collection, POST on a singleton resource, etc.

When to use it

REST APIs that want to be explicit about allowed verbs.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 405 Method Not Allowed

import requests
r = requests.get("https://example.com/path")
if r.status_code == 405:
    print("Method Not Allowed")

const r = await fetch("https://example.com/path");
if (r.status === 405) {
  console.log("Method Not Allowed");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 405);
// or:
http_response_code(405);

406 Not Acceptable #

The server cannot produce a representation matching the Accept-* headers. RFC 9110 §15.5.7.

Common cause

Client asked for application/xml but only application/json is available.

When to use it

Strict content negotiation. Many APIs default to JSON instead of returning 406.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 406 Not Acceptable

import requests
r = requests.get("https://example.com/path")
if r.status_code == 406:
    print("Not Acceptable")

const r = await fetch("https://example.com/path");
if (r.status === 406) {
  console.log("Not Acceptable");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 406);
// or:
http_response_code(406);

408 Request Timeout #

The server gave up waiting for the client to finish the request. RFC 9110 §15.5.9.

Common cause

Slow client connection, half-finished upload, idle keep-alive that exceeded the server timeout.

When to use it

Reverse proxies and load balancers fronting slow clients.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 408 Request Timeout

import requests
r = requests.get("https://example.com/path")
if r.status_code == 408:
    print("Request Timeout")

const r = await fetch("https://example.com/path");
if (r.status === 408) {
  console.log("Request Timeout");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 408);
// or:
http_response_code(408);

409 Conflict #

The request conflicts with the current state of the resource. RFC 9110 §15.5.10.

Common cause

Two clients edited the same record concurrently; unique-constraint violation; PUT with a stale ETag.

When to use it

Optimistic concurrency control, idempotent create endpoints.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 409 Conflict

import requests
r = requests.get("https://example.com/path")
if r.status_code == 409:
    print("Conflict")

const r = await fetch("https://example.com/path");
if (r.status === 409) {
  console.log("Conflict");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 409);
// or:
http_response_code(409);

410 Gone #

The resource was intentionally removed and will not return. RFC 9110 §15.5.11.

Common cause

Permanently deleted content; deprecated API endpoint that has been retired.

When to use it

Removed pages where you want crawlers to drop the URL faster than 404 would.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 410 Gone

import requests
r = requests.get("https://example.com/path")
if r.status_code == 410:
    print("Gone")

const r = await fetch("https://example.com/path");
if (r.status === 410) {
  console.log("Gone");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 410);
// or:
http_response_code(410);

411 Length Required #

The request lacks a Content-Length header where the server requires one. RFC 9110 §15.5.12.

Common cause

A streaming client that didn’t buffer the body or didn’t use chunked transfer encoding.

When to use it

Servers that disallow chunked uploads on certain endpoints.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 411 Length Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 411:
    print("Length Required")

const r = await fetch("https://example.com/path");
if (r.status === 411) {
  console.log("Length Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 411);
// or:
http_response_code(411);

413 Content Too Large #

The request body is larger than the server is willing to accept. RFC 9110 §15.5.14. Renamed from "Payload Too Large" in RFC 9110.

Common cause

Upload over the configured size limit, file beyond the maximum form size.

When to use it

File-upload endpoints, JSON APIs with body-size limits.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 413 Content Too Large

import requests
r = requests.get("https://example.com/path")
if r.status_code == 413:
    print("Content Too Large")

const r = await fetch("https://example.com/path");
if (r.status === 413) {
  console.log("Content Too Large");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 413);
// or:
http_response_code(413);

414 URI Too Long #

The request URI is longer than the server is willing to interpret. RFC 9110 §15.5.15.

Common cause

Massive query strings (often from forms submitted with method=GET) or URL-embedded tokens.

When to use it

When users hit your endpoint with abnormally long URLs — switch the form to POST.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 414 URI Too Long

import requests
r = requests.get("https://example.com/path")
if r.status_code == 414:
    print("URI Too Long")

const r = await fetch("https://example.com/path");
if (r.status === 414) {
  console.log("URI Too Long");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 414);
// or:
http_response_code(414);

415 Unsupported Media Type #

The server refuses to accept the body in the format described by the Content-Type header. RFC 9110 §15.5.16.

Common cause

Sending application/xml to a JSON-only endpoint, missing or wrong Content-Type.

When to use it

REST APIs that strictly accept only one or two media types.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 415 Unsupported Media Type

import requests
r = requests.get("https://example.com/path")
if r.status_code == 415:
    print("Unsupported Media Type")

const r = await fetch("https://example.com/path");
if (r.status === 415) {
  console.log("Unsupported Media Type");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 415);
// or:
http_response_code(415);

418 I’m a teapot #

An April-fools joke from RFC 2324 (HTCPCP). Some servers return it as a generic "refuse to brew" error. Not a real production status.

Common cause

Software that returns 418 deliberately, often to mark abuse traps or jokes.

When to use it

Easter eggs only. Don’t use in real APIs — many proxies and clients don’t recognise it.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 418 I’m a teapot

import requests
r = requests.get("https://example.com/path")
if r.status_code == 418:
    print("I’m a teapot")

const r = await fetch("https://example.com/path");
if (r.status === 418) {
  console.log("I’m a teapot");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 418);
// or:
http_response_code(418);

422 Unprocessable Content #

The syntax is fine but the server can’t process the semantic content. RFC 9110 §15.5.21. Originally introduced by WebDAV (RFC 4918).

Common cause

Validation errors on a structurally valid JSON payload — required field empty, value out of range.

When to use it

Form validation in modern APIs. Cleaner than 400 because the request is syntactically valid.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 422 Unprocessable Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 422:
    print("Unprocessable Content")

const r = await fetch("https://example.com/path");
if (r.status === 422) {
  console.log("Unprocessable Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 422);
// or:
http_response_code(422);

423 Locked #

The resource is locked. RFC 4918 (WebDAV).

Common cause

WebDAV resource that another user holds an exclusive lock on.

When to use it

Document collaboration servers, version-control front-ends.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 423 Locked

import requests
r = requests.get("https://example.com/path")
if r.status_code == 423:
    print("Locked")

const r = await fetch("https://example.com/path");
if (r.status === 423) {
  console.log("Locked");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 423);
// or:
http_response_code(423);

425 Too Early #

The server is unwilling to process a request that might be replayed, typically because it was sent in TLS 1.3 0-RTT (early data). RFC 8470.

Common cause

TLS 1.3 0-RTT request that the server treats as replay-unsafe.

When to use it

Protect non-idempotent endpoints from replay during 0-RTT handshakes.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 425 Too Early

import requests
r = requests.get("https://example.com/path")
if r.status_code == 425:
    print("Too Early")

const r = await fetch("https://example.com/path");
if (r.status === 425) {
  console.log("Too Early");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 425);
// or:
http_response_code(425);

428 Precondition Required #

The origin server requires the request to be conditional. RFC 6585.

Common cause

The server wants clients to use If-Match / If-Unmodified-Since to avoid lost-update conflicts.

When to use it

APIs with optimistic locking that refuse unconditional writes.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 428 Precondition Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 428:
    print("Precondition Required")

const r = await fetch("https://example.com/path");
if (r.status === 428) {
  console.log("Precondition Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 428);
// or:
http_response_code(428);

429 Too Many Requests #

The user has sent too many requests in a given time. RFC 6585.

Common cause

Rate limit hit; the response usually includes a Retry-After header.

When to use it

Rate-limited APIs, login throttling, abuse mitigation.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 429 Too Many Requests

import requests
r = requests.get("https://example.com/path")
if r.status_code == 429:
    print("Too Many Requests")

const r = await fetch("https://example.com/path");
if (r.status === 429) {
  console.log("Too Many Requests");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 429);
// or:
http_response_code(429);

431 Request Header Fields Too Large #

The server refuses to process the request because its header fields are too large. RFC 6585.

Common cause

An oversized cookie, an extremely long Referer or Authorization header.

When to use it

When session cookies grow beyond your reverse-proxy buffer; consider trimming or moving state to the body.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 431 Request Header Fields Too Large

import requests
r = requests.get("https://example.com/path")
if r.status_code == 431:
    print("Request Header Fields Too Large")

const r = await fetch("https://example.com/path");
if (r.status === 431) {
  console.log("Request Header Fields Too Large");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 431);
// or:
http_response_code(431);

451 Unavailable For Legal Reasons #

The resource is unavailable due to legal demands — a takedown order, geo-block, or DMCA. RFC 7725.

Common cause

Court order, regulator takedown, GDPR right-to-erasure response.

When to use it

Compliance teams that need to be transparent about why a page is blocked.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 451 Unavailable For Legal Reasons

import requests
r = requests.get("https://example.com/path")
if r.status_code == 451:
    print("Unavailable For Legal Reasons")

const r = await fetch("https://example.com/path");
if (r.status === 451) {
  console.log("Unavailable For Legal Reasons");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 451);
// or:
http_response_code(451);

500 Internal Server Error #

The server encountered an unexpected condition that prevented it from fulfilling the request. RFC 9110 §15.6.1.

Common cause

Unhandled exception, application bug, broken dependency, runaway query.

When to use it

Catch-all server error. Always log a stack trace and a request ID so users can quote it.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 500 Internal Server Error

import requests
r = requests.get("https://example.com/path")
if r.status_code == 500:
    print("Internal Server Error")

const r = await fetch("https://example.com/path");
if (r.status === 500) {
  console.log("Internal Server Error");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 500);
// or:
http_response_code(500);

501 Not Implemented #

The server does not support the functionality required to fulfil the request. RFC 9110 §15.6.2.

Common cause

Unknown method, feature flag disabled, code path stubbed.

When to use it

API endpoints that exist but are not yet built. Prefer 405 if the method is wrong but others work.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 501 Not Implemented

import requests
r = requests.get("https://example.com/path")
if r.status_code == 501:
    print("Not Implemented")

const r = await fetch("https://example.com/path");
if (r.status === 501) {
  console.log("Not Implemented");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 501);
// or:
http_response_code(501);

502 Bad Gateway #

The gateway or proxy got an invalid response from the upstream server. RFC 9110 §15.6.3.

Common cause

Upstream returned malformed HTTP, the connection broke mid-response, or the application crashed.

When to use it

Reverse proxies (Nginx, Cloudflare, ALB) when the application behind them fails.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 502 Bad Gateway

import requests
r = requests.get("https://example.com/path")
if r.status_code == 502:
    print("Bad Gateway")

const r = await fetch("https://example.com/path");
if (r.status === 502) {
  console.log("Bad Gateway");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 502);
// or:
http_response_code(502);

503 Service Unavailable #

The server is currently unable to handle the request, typically due to maintenance or overload. RFC 9110 §15.6.4.

Common cause

Maintenance window, the queue is full, autoscaler hasn’t caught up, deliberate brown-out.

When to use it

Planned downtime or overload protection. Always set Retry-After so clients can back off.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 503 Service Unavailable

import requests
r = requests.get("https://example.com/path")
if r.status_code == 503:
    print("Service Unavailable")

const r = await fetch("https://example.com/path");
if (r.status === 503) {
  console.log("Service Unavailable");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 503);
// or:
http_response_code(503);

504 Gateway Timeout #

The gateway or proxy did not get a timely response from the upstream server. RFC 9110 §15.6.5.

Common cause

Upstream took longer than the proxy’s configured timeout to respond.

When to use it

Slow application code, blocked database queries, third-party API hangs.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 504 Gateway Timeout

import requests
r = requests.get("https://example.com/path")
if r.status_code == 504:
    print("Gateway Timeout")

const r = await fetch("https://example.com/path");
if (r.status === 504) {
  console.log("Gateway Timeout");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 504);
// or:
http_response_code(504);

505 HTTP Version Not Supported #

The server does not support the major HTTP version of the request. RFC 9110 §15.6.6.

Common cause

Client speaks HTTP/2 to a server that only does HTTP/1.0, or sends an unrecognised version token.

When to use it

Rare in practice. Misconfigured edges or very old clients.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 505 HTTP Version Not Supported

import requests
r = requests.get("https://example.com/path")
if r.status_code == 505:
    print("HTTP Version Not Supported")

const r = await fetch("https://example.com/path");
if (r.status === 505) {
  console.log("HTTP Version Not Supported");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 505);
// or:
http_response_code(505);

511 Network Authentication Required #

The client must authenticate to use the network — typically a captive portal. RFC 6585.

Common cause

Hotel or airport Wi-Fi intercepting traffic until login.

When to use it

Captive portals on transient networks. Servers do not normally return this themselves.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 511 Network Authentication Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 511:
    print("Network Authentication Required")

const r = await fetch("https://example.com/path");
if (r.status === 511) {
  console.log("Network Authentication Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 511);
// or:
http_response_code(511);

What are HTTP status codes?

An HTTP status code is the three-digit number a server returns at the start of every response. It groups into five families: 1xx informational, 2xx success, 3xx redirection, 4xx client error and 5xx server error. The codes are defined in RFC 9110 (the consolidated 2022 spec replacing the older 7230–7235 series), with extensions in RFC 6585 (additional 4xx/5xx), RFC 7725 (451), RFC 4918 (WebDAV) and RFC 8470 (425). Reading the status correctly is the difference between fixing a bug in five minutes and chasing a ghost for an afternoon: a 404 from your CDN means the path is wrong, a 502 from your proxy means the application crashed, and a 401 with no WWW-Authenticate header is a misconfigured backend. This page is a searchable cheat sheet — each card includes the official name, an RFC-grounded description, the typical cause and concrete code snippets you can paste into curl, Python, JavaScript or PHP.

How to use the reference

Type a code or part of a name in the search box, or filter by family using the chips. Each card opens to reveal the technical description, common causes and a tabbed snippet you can adapt. Every code has its own anchor (e.g. #404) so you can deep-link team docs straight to a specific status.

Status code families at a glance

Range	Family	Meaning
1xx	Informational	Provisional responses; rarely seen at the application layer.
2xx	Success	Request was received, understood and accepted.
3xx	Redirection	Further action is needed (a different URL, cache validation, etc.).
4xx	Client error	The request had a problem (bad input, missing auth, wrong method).
5xx	Server error	The server failed to fulfil an apparently valid request.

Frequently asked questions

Where do these codes come from?

RFC 9110 is the canonical 2022 specification consolidating the older RFC 7231 series. Additional codes live in RFC 6585 (428, 429, 431, 511), RFC 7725 (451), RFC 4918 (WebDAV) and RFC 8470 (425).

Should I use 401 or 403?

401 means "you are not authenticated". 403 means "you are authenticated but not allowed". A 401 must include a WWW-Authenticate header listing accepted schemes; a 403 should not because the credentials are not the issue.

What’s the difference between 301 and 308?

Both signal a permanent redirect. 301 historically rewrites POST to GET in many clients, 308 explicitly preserves the method and body. Use 308 in new APIs.

When does my CDN return 502 vs 504?

502 (Bad Gateway) means the upstream returned malformed data or closed the connection. 504 (Gateway Timeout) means the upstream took too long. CloudFront, Cloudflare and Nginx tag them differently in logs — both indicate an application problem.

Should I return 404 or 410 for deleted content?

Use 410 when the resource was intentionally and permanently removed and you want crawlers to drop it fast. 404 is fine for typos and content that may come back; it’s also a defensible response for resources you don’t want to confirm exist.

Are the snippets safe to copy?

They are minimal templates intended for reading and adapting. Always validate input, handle errors and respect HTTP semantics in your own code — the samples skip those for brevity.