Códigos de estado HTTP Cuándo devolver 404 vs 410 vs 301 (y deje de adivinar)

Usted devolvió 200 con {"error": "user not found"} en el cuerpo. Sus 301s son en realidad 302s. Los recursos eliminados siguen devolviendo 404 para siempre. Vamos a revisar los códigos de estado que los desarrolladores suelen malinterpretar y qué deberían devolver en su lugar.

4xx vs 5xx: No son el mismo grupo

La división más fundamental en los códigos de estado HTTP: 4xx es culpa del cliente, 5xx es suya. Simple en teoría, violado constantemente en la práctica.

El más común: devolver 500 por un error de validación. Un usuario envió JSON malformado a su API. Eso es se usa para solicitudes que el servidor no puede parsear — JSON malformado, sintaxis incorrecta en la cadena de consulta, cabeceras requeridas faltantes. Es un problema estructural. — su carga de datos era incorrecta. Un 500 informa al cliente que “se produjo un error”, lo que desencadena alertas, se registra como un error del servidor y hace que los sistemas automatizados intenten nuevamente (lo que empeora aún más su día). Si el cliente envió datos incorrectos, diga lo claro con un 4xx.

404 vs 410: El problema del recurso eliminado

404 No Encontrado significa: “No la tengo ahora, pero tal vez intente de nuevo más tarde”. Los recolectores — incluyendo Googlebot — tratan a 404 como temporal. Se volverán a verificar indefinidamente.

410 Eliminado significa: “Este recurso fue eliminado permanentemente. Deje de pedirlo”. Googlebot elimina rápidamente las URLs 410 del índice y deja de recorrerlas antes. Esto importa para el SEO y para el presupuesto de recorrido en sitios grandes.

La regla práctica: si su API elimina un registro de forma definitiva y ya no regresa, devuelva 410 en las solicitudes posteriores. La única razón para preferir 404 en un recurso eliminado es si podría restaurarse — eliminación suave con un periodo de recuperación, un artículo publicado que podría volver a publicarse, etc. De lo contrario, 410 es más honesto y los motores de búsqueda lo agradecerán.

301 vs 302 (y por qué existen 307/308)

301 Movido Permanente: Esta URL ha desaparecido para siempre, use la nueva. Los navegadores almacenan los 301 de forma agresiva. Los motores de búsqueda transfieren el equilibrio de enlaces a la nueva URL. Si está consolidando dominios o moviendo permanentemente un sitio, 301 es lo que desea.

302 Encontrado: Vaya a esta otra URL por ahora, pero vuelva a la original más tarde. No hay caché. No hay transferencia de equilibrio de enlaces. Use esto para redirecciones de login, páginas de mantenimiento temporal o pruebas A/B.

El modo de fallo: usar 302 para movimientos permanentes. Piensa que “es lo mismo, solo diferente”, pero los motores de búsqueda no transfieren el equilibrio de enlaces a través de 302. Años de trabajo de SEO permanecen atados a la URL antigua mientras la nueva no se posiciona. Si ha movido algo permanentemente, use 301.

Luego hay 307 Redirección Temporal y 308 Redirección Permanente. Estos son variantes seguras en el método: donde un navegador podría reducir un POST a un GET al seguir una 301/302, las 307/308 preservan el método original. Si está redirigiendo puntos de entrada de API que aceptan cuerpos POST, 307 (temporal) o 308 (permanente) mantiene el método intacto.

Código	Tipo	Cachés?	Mantiene el método?	Use para
301	Permanente	Sí	No (puede reducirse a GET)	Movimientos permanentes de sitio, consolidación de URLs
302	Temporal	No	No (puede reducirse a GET)	Redirecciones de login, disponibilidad temporal
307	Temporal	No	Sí	Redirección temporal para puntos de entrada de API POST
308	Permanente	Sí	Sí	Redirección permanente para puntos de entrada de API POST

401 vs 403: Autenticación vs Autorización

El nombre es confuso. 401 No Autorizado de hecho significa no autenticado — no está registrado o sus credenciales están faltando o son inválidas. 403 Prohibido significa que está autenticado, pero no tiene permiso para acceder a este recurso.

La diferencia práctica: un 401 debe mostrar una pantalla de inicio de sesión o una actualización de token. Un 403 debe mostrar un mensaje de acceso denegado. Devolver el error incorrecto y el cliente no sabe si debe pedir credenciales o abandonar.

También hay una dimensión de seguridad. Algunas APIs devuelven 404 en lugar de 403 para recursos que no puede acceder el llamador, para evitar revelar que el recurso existe. Si devuelve 403 en un recurso de otro tenant, has confirmado que existe. Devolver 404 es más seguro en términos de información, aunque dificulta el diagnóstico para usuarios legítimos. Elija la opción que se ajuste a su modelo de amenaza y aplíquela de forma consistente.

429: Límite de velocidad, con la cabecera que realmente ayuda

Un simple 429 Demasiadas solicitudes es molesto. Un 429 con una Retry-After cabecera es realmente útil.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1746374400

Retry-After puede ser un número de segundos o una fecha HTTP. Los clientes bien comportados se detendrán automáticamente. Sin ella, está devolviendo un código de error y esperando que el cliente determine cuándo volver a intentarlo — la mayoría simplemente golpearán nuevamente su punto de entrada, lo que anula el propósito del límite de velocidad.

No devuelva 503 por límite de velocidad. 503 significa “servicio no disponible” — infraestructura caída, despliegue en progreso, circuit breaker abierto. El límite de velocidad es una decisión de política, no un fallo del servicio. 429 existe exactamente para este caso.

El patrón “200 con un cuerpo de error”

Este patrón sigue apareciendo en APIs en producción y debe detenerse:

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

{"status": "error", "message": "user not found"}

Esto rompe todo lo que depende de las semánticas de HTTP. Las herramientas de monitoreo reportan la solicitud como exitosa. Los equilibradores de carga la pasan. Las bibliotecas de clientes no lanzan errores. Los logs parecen limpios mientras los usuarios ven errores. La solución es una línea sencilla: devuelva el código de estado correcto. 200 significa que funcionó. Si no funcionó, no devuelva 200.

La misma lógica se aplica a 201 vs 200 para la creación de recursos. Si un POST a /users crea un nuevo usuario, devuelva 201 Creado con un Location cabecera que apunta al nuevo recurso. Devuelva 200 y habrá perdido información que sus clientes podrían usar para evitar un nuevo viaje.

Escenario de API → Código de estado correcto

Aquí hay una tabla de referencia para los escenarios que surgen más en el desarrollo de APIs REST:

Guión	Código de estado	Notas
El cuerpo de solicitud es JSON malformado	se usa para solicitudes que el servidor no puede parsear — JSON malformado, sintaxis incorrecta en la cadena de consulta, cabeceras requeridas faltantes. Es un problema estructural.	Incluya un mensaje que apunte al error de parseo
Campo faltante o inválido en la solicitud	se usa para solicitudes que el servidor entendió pero no puede actuar porque los datos fallan en la validación — un rango de fechas donde el inicio es después del final, un campo de correo electrónico con una dirección inválida, un campo de cantidad que es negativo. La solicitud era sintácticamente correcta. Los aspectos semánticos eran incorrectos.	422 es más preciso que 400 para fallos de validación semántica
Token de autenticación faltante o expirado	401 No Autorizado	Incluir WWW-Authenticate cabecera
Autenticado pero sin permisos	403 Prohibido	O 404 si es necesario ocultar la existencia del recurso
Recurso no encontrado, podría devolver	404 No Encontrado	Para ausencia temporal o recursos desconocidos
Recurso eliminado permanentemente	410 Eliminado	Los recolectores dejarán de verificar más temprano
Se creó un nuevo recurso	201 Creado	Añadir Location: /resources/new-id cabecera
DELETE se completó, sin cuerpo	— no 200 con cuerpo vacío, ni 200 con	No devuelva un objeto JSON vacío con 200
Cambio permanente de URL	301 Movido Permanente	Los motores de búsqueda transfieren el equilibrio de enlaces
Usa 307 si se debe conservar el método	302 Encontrado	Sin caché, sin transferencia de equilibrio
Se superó el límite de velocidad	429 Demasiadas solicitudes	Incluya siempre Retry-After
Excepción inesperada en el servidor	500 Error interno del servidor	No revele trazas de pila en el cuerpo
Dependencia superior caída	significa que el servidor al que llegaste no puede manejar la solicitud en este momento — está sobrecargado, en modo de mantenimiento o una dependencia de backend está inactiva. El servidor mismo respondió; simplemente lo rechaza.	Añadir Retry-After si la interrupción es limitada
Redirección POST, preserva el método	307 o 308	307 temporal, 308 permanente

Cuando está en medio de una PR y necesita verificar qué significa un código de estado, el Herramienta de búsqueda de códigos de estado HTTP le da la definición del especificación, casos de uso típicos y cuál RFC lo define.

Verificación de cadenas de redirección

Después de una migración de sitio o reestructuración de URL, vale la pena verificar la cadena completa de redirección — especialmente si tiene 301s que posteriormente se actualizaron para apuntar a otro lugar, creando cadenas de múltiples saltos que pierden el equilibrio de enlaces. El Verificador de redirecciones rastrea la cadena y muestra cada código de estado en secuencia, para que pueda confirmar que todo se resuelve en un solo salto.

También te puede interesar