HTTP-Statuscodes: vollständige Referenz und die häufigsten Verwechslungen

Eine Liste von Statuscodes auswendig zu lernen ist leicht; den richtigen auszuwählen ist der schwierige Teil. Der Unterschied zwischen „diesen Datensatz habe ich nicht gefunden“ und „du darfst diesen Datensatz nicht sehen“ in einer API, ob aus einem POST bei einer Weiterleitung ein GET wird, ob Google eine Adresse wegen einer Fehlerseite aus dem Index nimmt – alles hängt an der Wahl der richtigen dreistelligen Zahl.

Dieser Beitrag hat zwei Teile: zuerst eine vollständige Liste (zum Nachschlagen), dann die Codes, die in der Praxis am häufigsten falsch gewählt werden, und wie sie in Next.js in Erscheinung treten.

Fünf Klassen

Die Unterscheidung wirkt einfach, hat aber Grenzfälle: Der Client hat eine gültige Anfrage geschickt, der Server arbeitet korrekt, aber eine Geschäftsregel verbietet es – ist das 4xx oder 5xx? (Antwort: 4xx. Details weiter unten.)

1xx — Informational

In der Praxis ist 103 Early Hints der einzige moderne 1xx-Code, der wirklich nützlich ist: Während der Server die Hauptantwort vorbereitet, kann er dem Browser sagen: „Fang schon mal an, dieses CSS und diese Schrift zu laden.“

2xx — Successful

3xx — Redirection

Diese ganze Tabelle läuft auf eine einzige Unterscheidung hinaus: Bleibt die HTTP-Methode nach der Weiterleitung erhalten?

• 301 / 302 sind Legacy-Codes. Browser wandeln dabei POST-Anfragen in GET um – auch wenn die Spezifikation das nicht ausdrücklich vorsah, ist das der De-facto-Standard.
• 307 / 308 wurden eingeführt, um diese Mehrdeutigkeit zu beseitigen: Die verwendete Methode bleibt unverändert. Wenn du einen POST weiterleitest, geht er als POST weiter.
• 303 macht genau das Gegenteil mit Absicht: Es erzwingt die Methode GET, egal was hereinkam.

4xx — Client Error

401 oder 403?

Das am häufigsten verwechselte Paar. Die Namen führen in die Irre, denn 401 bedeutet eigentlich „nicht authentifiziert“:

• 401 – Ich weiß nicht, wer du bist. Melde dich an. (Keine Session oder ungültiges Token.)
• 403 – Ich weiß, wer du bist, aber auf diese Ressource darfst du nicht zugreifen. (Ein Nutzer mit der Rolle user, der /admin aufrufen will.)

400 oder 422?

• 400 – Ich konnte die Anfrage nicht parsen. Kaputtes JSON, fehlendes Pflichtfeld, falscher Datentyp.
• 422 – Ich habe sie geparst und das Format ist gültig, aber die Bedeutung ist ungültig. „Das Enddatum darf nicht vor dem Startdatum liegen“, „diese E-Mail-Adresse ist bereits registriert“.

Anders gesagt: Syntaxfehler sind 400, Verstöße gegen Geschäftsregeln sind 422. In der Praxis geben viele APIs für beides 400 zurück, das ist in Ordnung – aber wenn du sie trennst, können Client-Anwendungen „Formular korrigieren“ und „Anfrageformat korrigieren“ ohne zusätzlichen Code unterscheiden.

409 und 410

• 409 Conflict – Die Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource. Versionskonflikt bei gleichzeitiger Bearbeitung oder der Versuch, eine Ressource mit einem bereits vorhandenen Slug anzulegen.
• 410 Gone – Die Ressource existierte, wurde dauerhaft gelöscht und kommt nicht wieder. Der Unterschied zu 404 ist die Gewissheit: Suchmaschinen entfernen eine 410 deutlich schneller aus dem Index. Wenn du dir nicht sicher bist, bleib bei 404.

429 und Retry-After

Wenn du Rate Limiting implementierst, ist allein 429 zurückzugeben nur die halbe Arbeit. Sende auch einen Retry-After-Header – damit der Client weiß, wie lange er warten muss, statt blind erneut zu versuchen.

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

Wird verwendet, wenn Inhalte aus rechtlichen Gründen gesperrt sind. Benannt nach Ray Bradburys Roman Fahrenheit 451 – der Temperatur, bei der Papier brennt.

5xx — Server Error

502, 503, 504 – welcher Fehler ist welcher?

Diese drei sind der schnellste Weg, Probleme bei Server-Deployments zu diagnostizieren:

• 502 Bad Gateway – Nginx läuft, aber die App dahinter ist abgestürzt oder antwortet auf diesem Port nicht. Schau in die Logs deiner App.
• 503 Service Unavailable – Der Server läuft, verweigert aber gerade den Traffic: Wartungsmodus, Systemüberlastung, keine Instanz im Pool verfügbar. Sollte mit Retry-After gesendet und darf nicht gecacht werden.
• 504 Gateway Timeout – Die Upstream-App existiert, ist aber zu langsam; der Proxy hat das Warten aufgegeben. Such nach langsamen Queries oder langsamen Aufrufen externer APIs.

Statuscodes in Next.js

Das Framework wählt einige Statuscodes für dich aus, und es hilft zu wissen, was es im Hintergrund nimmt.

Wenn du eine Adresse dauerhaft änderst, nimm permanentRedirect() statt redirect() – oder setze permanent: true in der redirects()-Konfiguration deiner next.config.ts. Sonst nehmen Suchmaschinen die alte Adresse nicht aus dem Index.

notFound() gibt 404 zurück und rendert deine Datei not-found.tsx.

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}` },
	});
}

Schnelle Entscheidungshilfe

Eine letzte Anmerkung: Gib in Fehlerantworten niemals Stacktraces an Nutzer heraus. Statuscodes sagen dem Client, was er tun soll; detaillierte Informationen gehören in die Server-Logs.