HTTP durum kodları: tam referans ve pratikte en çok karıştırılanlar

Durum kodlarının listesini ezberlemek kolay; doğru olanı seçmek zor. Bir API'de "kaydı bulamadım" ile "bu kaydı görmeye yetkin yok" arasındaki fark, bir yönlendirmede POST'un GET'e dönüp dönmemesi, bir hata sayfasında Google'ın adresi indeksten silip silmemesi — hepsi bu üç haneli sayının seçimine bağlı.

Bu yazı iki bölüm: önce tam liste (referans olarak kullan), sonra pratikte en çok yanlış seçilen kodlar ve Next.js'te bunların nasıl karşımıza çıktığı.

Beş sınıf

Ayrım basit görünüyor ama sınırda kalan durumlar var: istemci geçerli bir istek gönderdi, sunucu da doğru çalışıyor, ama iş kuralı izin vermiyor — bu 4xx mi 5xx mi? (Cevap: 4xx. Aşağıda.)

1xx — Bilgi

103 Early Hints pratikte işe yarayan tek modern 1xx: sunucu asıl yanıtı hazırlarken tarayıcıya "şu CSS ve fontu şimdiden çekmeye başla" diyebiliyor.

2xx — Başarı

3xx — Yönlendirme

Bu tablonun tamamı tek bir ayrımdan ibaret: yönlendirme sonrası metot korunuyor mu?

• 301 / 302 eski kodlar. Tarayıcılar bunlarda POST'u GET'e çeviriyor — standart öyle demese de fiilî durum bu.
• 307 / 308 bu belirsizliği ortadan kaldırmak için geldi: metot ne ise o kalıyor. POST'a yönlendiriyorsan POST olarak gidiyor.
• 303 ise tam tersini kasten yapıyor: neyle geldiğine bakmadan GET'e çeviriyor.

4xx — İstemci hatası

401 mi 403 mü?

En çok karıştırılan çift. Adları yanıltıcı, çünkü 401 aslında "kimliği doğrulanmamış" demek:

• 401 — Sen kimsin bilmiyorum. Giriş yap. (Oturum yok ya da token geçersiz.)
• 403 — Kim olduğunu biliyorum, ama bu kaynağa erişemezsin. (user rolündeki biri /admin'e girmeye çalışıyor.)

400 mü 422 mi?

• 400 — İsteği ayrıştıramadım. Bozuk JSON, eksik zorunlu alan, yanlış tip.
• 422 — Ayrıştırdım, biçim doğru; ama anlamı geçersiz. "Bitiş tarihi başlangıçtan önce olamaz", "bu e-posta zaten kayıtlı".

Yani sözdizimi hatası 400, iş kuralı ihlali 422. Pratikte pek çok API ikisine de 400 döndürüyor ve bu da kabul edilebilir — ama ayırırsan istemci tarafında "formu düzelt" ile "isteği düzelt" ayrımını kod yazmadan yapabiliyorsun.

409 ve 410

• 409 Conflict — İstek kaynağın şu anki durumuyla çelişiyor. Eşzamanlı düzenlemede sürüm çakışması, aynı slug'ın ikinci kez oluşturulmaya çalışılması.
• 410 Gone — Kaynak vardı, kalıcı olarak silindi ve geri gelmeyecek. 404'ten farkı kesinlik: arama motorları 410 gördüğünde adresi daha hızlı düşürüyor. Emin değilsen 404 kullan.

429 ve Retry-After

Hız sınırlaması uyguluyorsan yalnız 429 döndürmek yarım iş. Retry-After başlığını da gönder — istemci ne kadar bekleyeceğini bilsin, körlemesine tekrar denemesin.

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", // saniye
				},
			}
		);
	}
 
	// ...
}

451

İçerik hukuki bir sebeple engellendiğinde. Ray Bradbury'nin Fahrenheit 451 romanına gönderme — kitapların yakıldığı sıcaklık. Türkiye'de erişim engelleri için de doğru koddur, ama uygulamada çoğu yerde kullanılmıyor.

5xx — Sunucu hatası

502, 503, 504 — hangisi hangi arıza?

Bu üçü sunucu kurulumunda teşhis koymanın en hızlı yolu:

• 502 Bad Gateway — Nginx ayakta, ama arkadaki uygulama çökmüş ya da o porta cevap vermiyor. Uygulama loglarına bak.
• 503 Service Unavailable — Sunucu ayakta ama şu an hizmet vermek istemiyor: bakım modu, aşırı yük, havuzda örnek yok. Retry-After ile birlikte gönderilmeli ve önbelleğe alınmamalı.
• 504 Gateway Timeout — Arkadaki uygulama var ama çok yavaş; ara sunucu beklemekten vazgeçti. Yavaş sorgu ya da dış API çağrısı ara.

Next.js'te durum kodları

Framework bazı kodları senin yerine seçiyor ve hangisini seçtiğini bilmek işe yarıyor.

Kalıcı bir adres değişikliği yapıyorsan redirect() değil permanentRedirect() kullan — ya da next.config.ts içindeki redirects() tanımında permanent: true ver. Aksi hâlde arama motoru eski adresi düşürmez.

notFound() çağrısı 404 döndürür ve not-found.tsx dosyanı gösterir.

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) {
		// Biçim doğru, anlam geçersiz
		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}` },
	});
}

Hızlı karar rehberi

Son bir not: hata gövdesinde kullanıcıya yığın izi (stack trace) gösterme. Durum kodu istemciye ne yapacağını söylemek için; ayrıntı loglara ait.