Códigos de estado HTTP: referencia completa y las confusiones más comunes

Memorizar una lista de códigos de estado es fácil; elegir el correcto es lo difícil. La diferencia entre "no pude encontrar este registro" y "no tienes permiso para ver este registro" en una API, que un POST se convierta en GET durante una redirección, que Google elimine una dirección de su índice por una página de error: todo se reduce a elegir el número de tres cifras adecuado.

Este artículo tiene dos partes: primero, una lista completa (úsala como referencia) y después los códigos que más se eligen mal en la práctica y cómo aparecen en Next.js.

Cinco clases

La distinción parece simple, pero hay casos límite: el cliente envió una solicitud válida, el servidor funciona correctamente, pero una regla de negocio lo prohíbe. ¿Es 4xx o 5xx? (Respuesta: 4xx. Detalles más abajo.)

1xx — Informativos

En la práctica, 103 Early Hints es el único 1xx moderno que realmente resulta útil: mientras el servidor prepara la respuesta principal, puede decirle al navegador "empieza a descargar este CSS y esta fuente por adelantado".

2xx — Éxito

3xx — Redirección

Toda esta tabla se resume en una sola distinción: ¿se conserva el método HTTP después de redirigir?

• 301 / 302 son códigos heredados. Los navegadores convierten las solicitudes POST en GET con ellos; aunque la especificación no lo dijera estrictamente, es el estándar de facto.
• 307 / 308 se introdujeron para aclarar esta ambigüedad: el método que se usó se mantiene sin cambios. Si rediriges un POST, se envía como POST.
• 303 hace justo lo contrario a propósito: fuerza el método a GET sin importar lo que llegó.

4xx — Error del cliente

¿401 o 403?

La pareja que más se confunde. Sus nombres inducen a error, porque 401 en realidad significa "no autenticado":

• 401 — No sé quién eres. Inicia sesión. (Sin sesión o con un token no válido.)
• 403 — Sé quién eres, pero no puedes acceder a este recurso. (Un usuario con el rol user intentando entrar a /admin.)

¿400 o 422?

• 400 — No pude interpretar la solicitud. JSON corrupto, falta un campo obligatorio, tipo de dato incorrecto.
• 422 — La interpreté y el formato es válido, pero el significado no lo es. "La fecha de fin no puede ser anterior a la de inicio", "este correo ya está registrado".

En otras palabras: un error de sintaxis es 400, una violación de una regla de negocio es 422. En la práctica, muchas APIs devuelven 400 para ambos, lo cual está bien; pero si los separas, las aplicaciones cliente pueden distinguir "corrige el formulario" de "corrige el formato de la solicitud" sin código adicional.

409 y 410

• 409 Conflict — La solicitud entra en conflicto con el estado actual del recurso. Un conflicto de versiones por edición concurrente, o intentar crear un recurso con un slug que ya existe.
• 410 Gone — El recurso existió, se eliminó de forma permanente y no volverá. La diferencia con 404 es la certeza: los motores de búsqueda desindexan un 410 mucho más rápido. Si no estás seguro, quédate con 404.

429 y Retry-After

Si implementas rate limiting, devolver solo 429 es la mitad del trabajo. Envía también una cabecera Retry-After, para que el cliente sepa cuánto esperar en lugar de reintentar a ciegas.

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

Se usa cuando el contenido se bloquea por motivos legales. Debe su nombre a la novela Fahrenheit 451 de Ray Bradbury, la temperatura a la que arde el papel.

5xx — Error del servidor

502, 503, 504: ¿qué fallo es cada uno?

Estos tres son la forma más rápida de diagnosticar problemas de despliegue en el servidor:

• 502 Bad Gateway — Nginx está activo, pero la app que hay detrás se ha caído o no responde en ese puerto. Revisa los logs de tu app.
• 503 Service Unavailable — El servidor está activo, pero se niega a atender tráfico ahora mismo: modo mantenimiento, sobrecarga del sistema, ninguna instancia disponible en el pool. Debe enviarse con Retry-After y no debe cachearse.
• 504 Gateway Timeout — La app upstream existe pero es demasiado lenta; el proxy dejó de esperar. Busca consultas lentas o llamadas lentas a APIs externas.

Códigos de estado en Next.js

El framework elige algunos códigos de estado por ti, y saber cuáles elige por debajo ayuda.

Si vas a hacer un cambio de dirección permanente, usa permanentRedirect() en lugar de redirect(), o define permanent: true dentro de la configuración redirects() de tu next.config.ts. De lo contrario, los motores de búsqueda no desindexarán la dirección antigua.

Llamar a notFound() devuelve 404 y renderiza tu archivo 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}` },
	});
}

Guía rápida de decisión

Una última nota: nunca expongas stack traces a los usuarios en las respuestas de error. Los códigos de estado le dicen al cliente qué acción tomar; los detalles granulares pertenecen a los logs del servidor.