HTTP Status Codes Cheat Sheet

A response starts with the protocol, the code and a reason phrase

HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
Content-Length: 1245
Cache-Control: max-age=60

<!doctype html>...

The first digit is the class

An unknown code falls back to its class

HTTP/1.1 299 Something New

# a client that does not know 299 treats it as 200
# an unknown 4xx is handled like 400, an unknown 5xx like 500

Print only the status code

curl -s -o /dev/null -w "%{http_code}\n" https://httpbingo.org/status/404

Show the status line and headers

curl -sI https://httpbingo.org/status/429 | head -3

Follow redirects and see every hop

curl -sIL "https://httpbingo.org/redirect-to?url=/status/204&status_code=301" | grep -iE "^(HTTP|location)"

Twenty codes cover nearly every real response

4xx blames the request, 5xx blames the server

Classes by number range

The client asks before sending a large body

PUT /uploads/video.mp4 HTTP/1.1
Host: api.example.com
Content-Length: 734003200
Expect: 100-continue

HTTP/1.1 100 Continue

HTTP/1.1 201 Created
Location: /uploads/video.mp4

curl adds the header for large uploads

curl -T video.mp4 https://api.example.com/uploads/
curl -H "Expect:" -T video.mp4 https://api.example.com/uploads/    # never wait
curl --expect100-timeout 0.5 -T video.mp4 https://api.example.com/uploads/

Upgrading an HTTP/1.1 connection to a WebSocket

GET /chat HTTP/1.1
Host: example.com
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

102 Processing is deprecated

HTTP/1.1 102 Processing

103 Early Hints lets the browser start loading assets early

HTTP/1.1 103 Early Hints
Link: </styles/main.css>; rel=preload; as=style
Link: <https://cdn.example.com>; rel=preconnect

HTTP/1.1 200 OK
Content-Type: text/html
Link: </styles/main.css>; rel=preload; as=style

104 Upload Resumption Supported is provisional

HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/b530ce8ff

The default success, with a body

GET /users/42 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "Ana"}

A 200 that reports an error is a bug

HTTP/1.1 200 OK
Content-Type: application/json

{"success": false, "error": "User not found"}

Return the new resource and its URL

POST /users HTTP/1.1
Content-Type: application/json

{"name": "Ana"}

HTTP/1.1 201 Created
Location: /users/43
Content-Type: application/json

{"id": 43, "name": "Ana"}

Accept work that finishes later

POST /reports HTTP/1.1

HTTP/1.1 202 Accepted
Location: /reports/jobs/9f3a
Retry-After: 10

{"status": "queued", "check": "/reports/jobs/9f3a"}

Success with nothing to return

DELETE /users/43 HTTP/1.1

HTTP/1.1 204 No Content

Range requests resume downloads and stream video

GET /video.mp4 HTTP/1.1
Range: bytes=0-1048575

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1048575/73400320
Content-Length: 1048576
Accept-Ranges: bytes

Ask for the last bytes of a file

curl -s -r -16 -D - -o /dev/null https://httpbingo.org/range/1024 | grep -iE "^(HTTP|content-range)"

203, 205, 207, 208 and 226

Permanent or temporary, and does the method survive

Every redirect needs a Location header

HTTP/1.1 301 Moved Permanently
Location: https://example.com/new-page
Content-Length: 0

Post, redirect, get

POST /orders HTTP/1.1
Content-Type: application/x-www-form-urlencoded

item=42&qty=1

HTTP/1.1 303 See Other
Location: /orders/8812

A conditional GET answered from the cache

GET /logo.png HTTP/1.1
If-None-Match: "33a64df5"

HTTP/1.1 304 Not Modified
ETag: "33a64df5"
Cache-Control: max-age=3600

curl stops after too many hops

curl -sL --max-redirs 5 -o /dev/null -w "%{http_code} after %{num_redirects} hops\n" https://httpbingo.org/redirect/10; echo "exit $?"

The proxy loop, and its fix

# the app sees http because TLS ends at the load balancer, so it redirects forever
if ($http_x_forwarded_proto = "http") {
    return 301 https://$host$request_uri;
}

300, 305 and 306

The request cannot be understood

POST /users HTTP/1.1
Content-Type: application/json

{"name": "Ana",}

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{"title": "Malformed JSON", "status": 400, "detail": "Unexpected token } at position 15"}

401 means who are you, 403 means you may not

GET /admin/reports HTTP/1.1

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"

GET /admin/reports HTTP/1.1
Authorization: Bearer eyJhbGciOi...

HTTP/1.1 403 Forbidden

Hide a resource's existence with 404

GET /orgs/acme/secret-project HTTP/1.1
Authorization: Bearer eyJhbGciOi...

HTTP/1.1 404 Not Found

Nothing at this URL, maybe ever

GET /products/does-not-exist HTTP/1.1

HTTP/1.1 404 Not Found
Content-Type: text/html
Cache-Control: max-age=300

The URL exists, the method does not

DELETE /users HTTP/1.1

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST

402, 406, 407, 408

The request clashes with the current state

POST /users HTTP/1.1
Content-Type: application/json

{"email": "ana@example.com"}

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{"title": "Email already registered", "status": 409}

Removed on purpose, not coming back

GET /promo/summer-2024 HTTP/1.1

HTTP/1.1 410 Gone

Someone else changed it first

PUT /docs/7 HTTP/1.1
If-Match: "v41"
Content-Type: application/json

{"title": "New title"}

HTTP/1.1 412 Precondition Failed
ETag: "v42"

413, 414, 415 and 431

Each library spells the reason phrase its own way

node -e "const h=require('http'); console.log(h.STATUS_CODES[413], '|', h.STATUS_CODES[422])"
python -c "from http import HTTPStatus as S; print(S(413).phrase, '|', S(422).phrase)"

Range Not Satisfiable states the real size

GET /file.zip HTTP/1.1
Range: bytes=9000000-

HTTP/1.1 416 Range Not Satisfiable
Content-Range: bytes */1048576

418 is a joke the spec keeps reserved

curl -s -o /dev/null -w "%{http_code}\n" https://httpbingo.org/status/418

Well formed, but the values are wrong

POST /users HTTP/1.1
Content-Type: application/json

{"email": "not-an-email", "age": -3}

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    {"field": "email", "detail": "must be a valid email address"},
    {"field": "age", "detail": "must be 0 or more"}
  ]
}

Rate limited, with a time to wait

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/problem+json

{"title": "Rate limit exceeded", "status": 429, "detail": "100 requests per minute"}

Some limits are not 429

HTTP/1.1 403 Forbidden
x-ratelimit-remaining: 0

HTTP/1.1 503 Service Unavailable
Retry-After: 120

421, 423, 424, 425, 426 and 428

Blocked by law, with an optional pointer to who demanded it

HTTP/1.1 451 Unavailable For Legal Reasons
Link: <https://authority.example/>; rel="blocked-by"
Content-Type: text/html

<p>This content is not available in your country.</p>

Something failed that the server did not expect

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json

{"title": "Internal Server Error", "status": 500, "instance": "/orders/8812", "traceId": "4bf92f3577b34da6"}

Three gateway errors that mean different things

503 with Retry-After for planned downtime

HTTP/1.1 503 Service Unavailable
Retry-After: 3600
Content-Type: text/html
Cache-Control: no-store

501, 505 to 511

510 is obsolete

HTTP/1.1 510 Not Extended

Codes nginx uses internally and in its logs

Drop junk requests silently

server {
    listen 80 default_server;
    server_name _;
    return 444;
}

52x codes mean Cloudflare could not get a good answer from your origin

Codes only an ALB generates

Framework and vendor codes outside the registry

Pick by what the client can do next

Four questions, one code

Who should answer with what

Success and common error codes for CRUD

DELETE twice: 204, then 404

DELETE /items/7 HTTP/1.1

HTTP/1.1 204 No Content

DELETE /items/7 HTTP/1.1

HTTP/1.1 404 Not Found

Report a result per item

POST /items/batch HTTP/1.1

HTTP/1.1 207 Multi-Status
Content-Type: application/json

{"results": [
  {"id": 1, "status": 201},
  {"id": 2, "status": 422, "detail": "price must be positive"}
]}

Poll a job until it finishes

GET /jobs/9f3a HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "running", "progress": 0.4}

GET /jobs/9f3a HTTP/1.1

HTTP/1.1 303 See Other
Location: /reports/2026-10

What load balancers and Kubernetes expect

GET /healthz HTTP/1.1

HTTP/1.1 200 OK
Content-Type: text/plain

ok

One JSON shape for every error

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 403,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/msgs/abc",
  "balance": 30
}

The members

List every invalid field at once

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/validation",
  "title": "Your request is not valid.",
  "status": 422,
  "errors": [
    {"pointer": "#/email", "detail": "must be a valid email address"},
    {"pointer": "#/items/0/qty", "detail": "must be at least 1"}
  ]
}

Frameworks that emit RFC 9457 for you

// ASP.NET Core: problem details for exceptions and empty error responses
builder.Services.AddProblemDetails();
app.UseExceptionHandler();
app.UseStatusCodePages();

Spring Boot

spring.mvc.problemdetails.enabled=true

Leaks and dead ends

HTTP/1.1 500 Internal Server Error

{"error": "SQLSTATE[42S02]: Base table 'prod.users_v2' doesn't exist at /var/www/app/db.php:88"}

Code, header, and how strict the spec is

Two formats, both valid

HTTP/1.1 503 Service Unavailable
Retry-After: 120

HTTP/1.1 429 Too Many Requests
Retry-After: Wed, 14 Oct 2026 18:30:00 GMT

Deprecation and Sunset headers

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://api.example.com/v2/orders>; rel="successor-version"

Tell clients what they can send

HTTP/1.1 415 Unsupported Media Type
Accept-Post: application/json, application/merge-patch+json

HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD, QUERY
Accept-Query: application/sql, application/jsonpath

Caches may store these without explicit Cache-Control

Stop a redirect or error from being cached

HTTP/1.1 301 Moved Permanently
Location: https://example.com/new
Cache-Control: no-store

HTTP/1.1 404 Not Found
Cache-Control: max-age=60

First request, then a conditional one

GET /api/config HTTP/1.1

HTTP/1.1 200 OK
ETag: "a1b2c3"
Cache-Control: no-cache

GET /api/config HTTP/1.1
If-None-Match: "a1b2c3"

HTTP/1.1 304 Not Modified
ETag: "a1b2c3"

See a 304 with curl

curl -s -o /dev/null -w "%{http_code}\n" -H 'If-None-Match: "abc"' "https://httpbingo.org/etag/abc"

If-Match turns lost updates into 412

A retry policy by status code

Wait longer after each failure, with randomness

const RETRY = new Set([408, 425, 429, 500, 502, 503, 504]);

async function fetchWithRetry(url, options = {}, tries = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, options);
    if (!RETRY.has(res.status) || attempt === tries - 1) return res;
    const header = res.headers.get("retry-after");
    let wait = Math.min(30000, 500 * 2 ** attempt) * Math.random();
    if (header) {
      const secs = Number(header);
      wait = Number.isNaN(secs) ? Date.parse(header) - Date.now() : secs * 1000;
    }
    await new Promise((r) => setTimeout(r, Math.max(0, wait)));
  }
}

The common header families

HTTP/1.1 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1792000000

HTTP/1.1 200 OK
RateLimit-Policy: "default";q=100;w=60
RateLimit: "default";r=37;t=21

What each class does to indexing

A missing page must not answer 200

HTTP/1.1 200 OK
Content-Type: text/html

<h1>Sorry, we could not find that product</h1>

Every URL in a sitemap should answer 200

curl -s https://example.com/sitemap.xml | grep -o "<loc>[^<]*" | cut -c6- | head -20 | xargs -I {} curl -s -o /dev/null -w "%{http_code} {}\n" {}

Its status code changes how the whole site is crawled

Fail the script on 4xx and 5xx

curl -sf https://httpbingo.org/status/503 > /dev/null; echo "exit $?"

Branch on the code in bash

code=$(curl -s -o /dev/null -w "%{http_code}" https://httpbingo.org/status/201)
case "$code" in
  2??) echo "ok: $code" ;;
  4??) echo "client error: $code" ;;
  5??) echo "server error: $code" ;;
  *)   echo "no HTTP response: $code" ;;
esac

Retry transient errors automatically

curl --retry 5 --retry-max-time 60 -sf https://api.example.com/health

Where would this redirect go

curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" "https://httpbingo.org/redirect-to?url=https://example.com/&status_code=308"

Count the hops and print the final URL

curl -sL -o /dev/null -w "%{num_redirects} hops, final %{http_code} at %{url_effective}\n" https://httpbingo.org/redirect/3

Check a list of URLs in parallel

xargs -P 8 -I {} curl -s -o /dev/null -w "%{http_code} {}\n" {} < urls.txt | sort

fetch resolves on 404 and 500

const res = await fetch("https://httpbingo.org/status/404");
console.log(res.status, res.ok, res.statusText);

const r2 = await fetch("https://httpbingo.org/status/204");
console.log(r2.status, r2.ok);

Turn HTTP errors into exceptions

async function getJson(url) {
  const res = await fetch(url, { headers: { Accept: "application/json" } });
  if (!res.ok) {
    const body = await res.text();
    throw new Error(`HTTP ${res.status} for ${url}: ${body.slice(0, 200)}`);
  }
  return res.status === 204 ? null : res.json();
}

statusText is empty over HTTP/2 and HTTP/3

console.log(res.status, JSON.stringify(res.statusText));   // 404 ""

Browsers hide manual redirects, Node.js does not

const res = await fetch("https://httpbingo.org/redirect-to?url=/get&status_code=302", { redirect: "manual" });
console.log(res.status, res.type, res.headers.get("location"));

const followed = await fetch("https://httpbingo.org/redirect/2");
console.log(followed.status, followed.redirected, followed.url);

A CORS failure has no status at all

fetch("https://other-site.example/api")
  .then((res) => console.log(res.status))
  .catch((err) => console.log(err.name, err.message));
// TypeError Failed to fetch

Reading codes in the browser

Express

app.post("/users", (req, res) => {
  const user = createUser(req.body);
  res.status(201).location(`/users/${user.id}`).json(user);
});

Next.js App Router route handler

export async function POST(request) {
  const user = await createUser(await request.json());
  return Response.json(user, { status: 201, headers: { Location: `/api/users/${user.id}` } });
}

Flask and FastAPI

# Flask: return body, status, headers
@app.post("/users")
def create_user():
    user = save(request.get_json())
    return user, 201, {"Location": f"/users/{user['id']}"}

# FastAPI: declare the success code on the route
@app.post("/users", status_code=status.HTTP_201_CREATED)
def create_user(user: UserIn, response: Response):
    saved = save(user)
    response.headers["Location"] = f"/users/{saved.id}"
    return saved

Spring Boot

@PostMapping("/users")
ResponseEntity<User> create(@RequestBody User user) {
    User saved = repository.save(user);
    return ResponseEntity.created(URI.create("/users/" + saved.getId())).body(saved);
}

Go 1.22 and later

mux.HandleFunc("POST /users", func(w http.ResponseWriter, r *http.Request) {
	user := createUser(r)
	w.Header().Set("Location", fmt.Sprintf("/users/%d", user.ID))
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated)
	json.NewEncoder(w).Encode(user)
})

PHP and Laravel

// plain PHP
http_response_code(201);
header("Location: /users/{$user['id']}");
header('Content-Type: application/json');
echo json_encode($user);

// Laravel
return response()->json($user, 201)->header('Location', "/users/{$user->id}");

ASP.NET Core minimal API

app.MapPost("/users", (UserIn input, AppDb db) =>
{
    var user = db.Add(input);
    return TypedResults.Created($"/users/{user.Id}", user);
});

Ruby on Rails

def create
  @user = User.create!(user_params)
  render json: @user, status: :created, location: @user
end

Express

app.get("/users/:id", (req, res) => {
  const user = findUser(req.params.id);
  if (!user) return res.status(404).json({ title: "User not found", status: 404 });
  res.json(user);
});
app.delete("/users/:id", (req, res) => { removeUser(req.params.id); res.sendStatus(204); });

Flask, FastAPI and Django

abort(404)                                             # Flask
raise HTTPException(status_code=404, detail="User not found")  # FastAPI
raise Http404("User not found")                        # Django
return JsonResponse({"error": "conflict"}, status=409) # Django

Spring Boot

@GetMapping("/users/{id}")
User get(@PathVariable long id) {
    return repository.findById(id)
        .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "User not found"));
}

@DeleteMapping("/users/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
void delete(@PathVariable long id) { repository.deleteById(id); }

Go

http.Error(w, "user not found", http.StatusNotFound)

PHP and Laravel

http_response_code(404);   // plain PHP
abort(404);                // Laravel
abort(403, 'Not allowed');
return response()->noContent();   // 204

ASP.NET Core

app.MapGet("/users/{id}", (int id, AppDb db) =>
    db.Find(id) is { } user ? Results.Ok(user) : Results.NotFound());

app.MapGet("/status", () => Results.Problem(statusCode: 503, title: "Down for maintenance"));

Rails

head :no_content
render json: { error: "conflict" }, status: :conflict
raise ActiveRecord::RecordNotFound   # rendered as 404 in production

Express and Next.js

res.redirect("/login");            // 302 by default
res.redirect(301, "/new-page");
// Next.js: redirect() sends 307, permanentRedirect() sends 308

Flask, FastAPI and Django

return redirect("/new-page", code=301)          # Flask, default 302
return RedirectResponse("/new-page", status_code=301)  # FastAPI, default 307
return redirect("/new-page", permanent=True)    # Django, default 302

Spring

return "redirect:/orders/" + id;        // 302 from a @Controller
return ResponseEntity.status(HttpStatus.SEE_OTHER).location(URI.create("/orders/" + id)).build();

Go

http.Redirect(w, r, "/new-page", http.StatusMovedPermanently)

PHP and Laravel

header('Location: /new-page', true, 301);   // without a code PHP sends 302
exit;
return redirect('/new-page', 301);           // Laravel, default 302

ASP.NET Core

Results.Redirect("/new-page");                       // 302
Results.Redirect("/new-page", permanent: true);      // 301
Results.Redirect("/new-page", permanent: true, preserveMethod: true);  // 308

Rails

redirect_to "/new-page"                               # 302
redirect_to "/new-page", status: :moved_permanently  # 301
redirect_to order_path(@order), status: :see_other   # 303, after a form

Node.js http sends the reason phrase for you

const http = require("http");
const server = http.createServer((req, res) => {
  res.writeHead(418, { "Content-Type": "text/plain" });
  res.end("short and stout");
});
server.listen(0, async () => {
  const res = await fetch(`http://localhost:${server.address().port}/`);
  console.log(res.status, res.statusText, await res.text());
  server.close();
});

Python urllib raises on 4xx and 5xx

import urllib.request, urllib.error

try:
    urllib.request.urlopen("https://httpbingo.org/status/404")
except urllib.error.HTTPError as e:
    print(e.code, e.reason)

from http import HTTPStatus
s = HTTPStatus(429)
print(s.value, s.phrase, s.is_client_error, s.is_server_error)

node:test with fetch, no extra packages

const test = require("node:test");
const assert = require("node:assert");
const http = require("http");

const app = http.createServer((req, res) => {
  if (req.method === "POST" && req.url === "/items") {
    res.writeHead(201, { Location: "/items/42" });
    return res.end();
  }
  res.writeHead(404).end();
});

test("POST /items answers 201 with a Location", async (t) => {
  await new Promise((resolve) => app.listen(0, resolve));
  t.after(() => app.close());
  const base = `http://localhost:${app.address().port}`;
  const res = await fetch(`${base}/items`, { method: "POST" });
  assert.strictEqual(res.status, 201);
  assert.strictEqual(res.headers.get("location"), "/items/42");
  assert.strictEqual((await fetch(`${base}/nope`)).status, 404);
});

pytest with the Flask or FastAPI test client

def test_create_item(client):
    r = client.post("/items", json={"name": "lamp"})
    assert r.status_code == 201
    assert r.headers["Location"] == "/items/42"

def test_missing_item(client):
    assert client.get("/items/999").status_code == 404

Spring MockMvc

mockMvc.perform(post("/items")
        .contentType(MediaType.APPLICATION_JSON)
        .content("{\"name\":\"lamp\"}"))
    .andExpect(status().isCreated())
    .andExpect(header().string("Location", "/items/42"));

mockMvc.perform(get("/items/999")).andExpect(status().isNotFound());

Playwright API checks

test("create and read an item", async ({ request }) => {
  const created = await request.post("/api/items", { data: { name: "lamp" } });
  expect(created.status()).toBe(201);
  const item = await request.get(created.headers()["location"]);
  await expect(item).toBeOK();
});

Check the code, then raise for errors

import requests

r = requests.get("https://httpbingo.org/status/503", timeout=10)
print(r.status_code, r.ok, r.reason)
try:
    r.raise_for_status()
except requests.HTTPError as e:
    print("HTTPError:", e)

Postman test script

pm.test("created", () => {
  pm.response.to.have.status(201);
  pm.response.to.have.header("Location");
});

k6 load test with a status check

import http from "k6/http";
import { check } from "k6";

export default function () {
  const res = http.get("https://test.k6.io/");
  check(res, { "status is 200": (r) => r.status === 200 });
}

Redirects

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

location = /old-page { return 301 /new-page; }
rewrite ^/blog/(.*)$ /articles/$1 permanent;   # 301; redirect flag gives 302

Error pages and changed codes

error_page 404 /errors/404.html;
error_page 502 503 504 /errors/50x.html;
location /errors/ { internal; }

error_page 404 =200 /empty.gif;     # answer 200 instead
proxy_intercept_errors on;          # also use them for upstream errors

Size limits, rate limits and timeouts

client_max_body_size 50m;            # default 1m, beyond it 413

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
location /api/ {
    limit_req zone=api burst=20 nodelay;
    limit_req_status 429;            # default 503
    proxy_read_timeout 120s;         # default 60s, then 504
    proxy_pass http://app:8080;
}

Redirects in .htaccess

Redirect 301 /old-page /new-page
RedirectMatch 301 ^/blog/(.*)$ /articles/$1

RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

Error documents

ErrorDocument 404 /errors/404.html
ErrorDocument 500 "Something went wrong. Please try again later."

Redirects, errors and fixed responses

example.com {
    redir /old-page /new-page 301
    respond /healthz 200
    handle_errors {
        rewrite * /errors/{err.status_code}.html
        file_server
    }
    reverse_proxy app:8080
}

Read the response headers, not just the code

HTTP/1.1 502 Bad Gateway
Server: cloudflare
CF-RAY: 8d2c1f0e9a7b1234-LHR

HTTP/1.1 504 Gateway Time-out
Server: nginx/1.28.0
Content-Type: text/html

<html><body><center><h1>504 Gateway Time-out</h1></center><hr><center>nginx/1.28.0</center></body></html>

Match the error log line to the fix

Two views of the same slow request

# nginx access log
10.0.0.5 - - [14/Oct/2026:18:22:41 +0000] "GET /report HTTP/1.1" 499 0 "-" "curl/8.19.0"

The code arrives as the :status pseudo-header

const http2 = require("http2");
const client = http2.connect("https://github.com");
const req = client.request({ ":path": "/this-page-does-not-exist" });
req.on("response", (headers) => {
  console.log(headers[":status"], headers["content-type"]);
  client.close();
});
req.end();

curl prints the protocol and no reason phrase

$ curl -sI https://github.com | head -1
HTTP/2 200

gRPC answers HTTP 200 and puts its own code in a trailer

GraphQL errors often travel in a 200

HTTP/1.1 200 OK
Content-Type: application/json

{"data": {"user": null}, "errors": [{"message": "User not found", "path": ["user"]}]}

WebSocket close codes are not HTTP codes

Which codes, how often

awk '{print $9}' access.log | sort | uniq -c | sort -rn | head -8

The share of server errors

awk '{n++} $9 ~ /^5/ {e++} END {printf "%d of %d requests were 5xx (%.1f%%)\n", e, n, 100 * e / n}' access.log

The URLs behind the errors

awk '$9 >= 500 {print $9, $7}' access.log | sort | uniq -c | sort -rn

5xx ratio over five minutes

sum(rate(http_requests_total{code=~"5.."}[5m]))
  /
sum(rate(http_requests_total[5m]))

An alerting rule

groups:
  - name: http
    rules:
      - alert: HighErrorRate
        expr: sum(rate(http_requests_total{code=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) > 0.02
        for: 10m
        labels:
          severity: page
        annotations:
          summary: "More than 2% of requests fail with 5xx"

What 99.9% allows

First checks for 4xx

First checks for 5xx

The documents that matter

Names changed in RFC 9110 and before