HTTP status codes: complete reference and most common confusion

Memorizing a list of status codes is easy; picking the right one is the hard part. The difference between "couldn't find this record" and "you don't have permission to see this record" in an API, whether a POST turns into a GET during a redirect, whether Google drops an address from its index on an error page — it all comes down to choosing the right three-digit number.

This post has two parts: first, a complete list (use it as a reference), then the codes most commonly picked wrong in practice and how they show up in Next.js.

Five classes

The distinction looks simple, but there are edge cases: the client sent a valid request, the server is working correctly, but a business rule forbids it — is that 4xx or 5xx? (Answer: 4xx. Details below.)

1xx — Informational

In practice, 103 Early Hints is the only modern 1xx that's actually useful: while the server prepares the main response, it can tell the browser "start fetching this CSS and font ahead of time."

2xx — Successful

3xx — Redirection

This entire table boils down to one distinction: is the HTTP method preserved after redirecting?

• 301 / 302 are legacy codes. Browsers convert POST requests to GET on these — even if the spec didn't strictly say so, that's the de facto standard.
• 307 / 308 were introduced to clear up this ambiguity: whatever method was used stays unchanged. If you redirect a POST, it goes as a POST.
• 303 does the exact opposite on purpose: it forces the method to GET regardless of what came in.

4xx — Client Error

401 or 403?

The most frequently confused pair. Their names are misleading, because 401 actually means "unauthenticated":

• 401 — I don't know who you are. Log in. (No session or invalid token.)
• 403 — I know who you are, but you can't access this resource. (A user with the user role trying to access /admin.)

400 or 422?

• 400 — I couldn't parse the request. Corrupted JSON, missing required field, wrong data type.
• 422 — I parsed it and the format is valid, but the meaning is invalid. "End date cannot be before start date", "this email is already registered".

In other words: syntax error is 400, business rule violation is 422. In practice, many APIs return 400 for both, which is fine — but if you separate them, client applications can handle "fix the form" vs "fix the request format" without extra code.

409 and 410

• 409 Conflict — The request conflicts with the current state of the resource. Concurrent editing version conflict, trying to create a resource with a slug that already exists.
• 410 Gone — The resource existed, was permanently deleted, and won't come back. The difference from 404 is certainty: search engines deindex a 410 much faster. If you're not sure, stick to 404.

429 and Retry-After

If you implement rate limiting, returning 429 alone is only half the job. Send a Retry-After header too — so the client knows how long to wait instead of blindly retrying.

export async function POST(req: Request) {
	const allowed = await rateLimit(req);
 
	if (!allowed) {
		return new Response(
			JSON.stringify({ error: "Çok fazla istek gönderdiniz." }),
			{
				status: 429,
				headers: {
					"Content-Type": "application/json",
					"Retry-After": "60", // seconds
				},
			}
		);
	}
 
	// ...
}

451

Used when content is blocked for legal reasons. Named after Ray Bradbury's novel Fahrenheit 451 — the temperature at which paper burns.

5xx — Server Error

502, 503, 504 — which failure is which?

These three are the fastest way to diagnose server deployment issues:

• 502 Bad Gateway — Nginx is up, but the app behind it has crashed or isn't responding on that port. Check your app logs.
• 503 Service Unavailable — Server is up, but refuses to serve traffic right now: maintenance mode, system overload, no instance available in pool. Should be sent with Retry-After and must not be cached.
• 504 Gateway Timeout — Upstream app exists but is too slow; proxy gave up waiting. Look for slow queries or slow external API calls.

Status codes in Next.js

The framework chooses some status codes for you, and knowing what it picks under the hood helps.

If you are making a permanent address change, use permanentRedirect() instead of redirect() — or set permanent: true inside your next.config.ts redirects() config. Otherwise, search engines won't deindex the old address.

Calling notFound() returns 404 and renders your not-found.tsx file.

import { NextResponse } from "next/server";
 
export async function POST(req: Request) {
	const body = await req.json().catch(() => null);
 
	if (!body) {
		return NextResponse.json({ error: "Geçersiz JSON" }, { status: 400 });
	}
 
	const parsed = schema.safeParse(body);
	if (!parsed.success) {
		// Valid format, invalid meaning
		return NextResponse.json(
			{ error: "Doğrulama hatası", issues: parsed.error.issues },
			{ status: 422 }
		);
	}
 
	const session = await auth();
	if (!session) {
		return NextResponse.json({ error: "Giriş gerekli" }, { status: 401 });
	}
	if (session.user.role !== "admin") {
		return NextResponse.json({ error: "Yetkiniz yok" }, { status: 403 });
	}
 
	const created = await db.post.create({ data: parsed.data });
 
	return NextResponse.json(created, {
		status: 201,
		headers: { Location: `/api/posts/${created.id}` },
	});
}

Quick decision guide

One final note: never expose stack traces to users in error responses. Status codes tell the client what action to take; granular details belong in server logs.