Códigos de estado HTTP

Un estándar con tres décadas de deriva

Los códigos de estado HTTP han vivido varias generaciones de la especificación. El RFC 1945 (mayo de 1996) estandarizó HTTP/1.0 con las categorías básicas 1xx-5xx. El RFC 2616 (junio de 1999) publicó HTTP/1.1 y fue la referencia canónica durante más de una década. La serie 7230-7235 (junio de 2014) dividió HTTP/1.1 en varias especificaciones por temas. El estándar consolidado actual es el RFC 9110 «HTTP Semantics» (junio de 2022), que deja obsoleta la división 7230-7235 y es la referencia adecuada para el trabajo moderno. El registro completo y vigente de los códigos asignados está en el registro de códigos de estado HTTP de IANA.

Las cinco categorías de un vistazo

• 1xx Informativo: respuesta provisional. La petición se recibió y el servidor sigue procesándola. Poco frecuente en la práctica; útil para las actualizaciones de protocolo y el moderno 103 Early Hints (que permite a los servidores precargar recursos críticos antes de que la respuesta completa esté lista).
• 2xx Éxito: la petición se recibió, se entendió y se aceptó. 200 OK es el caso de cada día; 201 Created para la creación de recursos; 204 No Content para acciones correctas que no devuelven nada.
• 3xx Redirección: se necesita una acción adicional. Las redirecciones clásicas (301 Moved Permanently, 302 Found, 307 Temporary Redirect, 308 Permanent Redirect) más 304 Not Modified para la validación de caché.
• 4xx Error del cliente: el cliente hizo algo mal: sintaxis incorrecta, falta de autenticación, solicitar algo que no existe. La categoría más grande en el tráfico real.
• 5xx Error del servidor: el servidor metió la pata. La petición era válida; el servidor simplemente no pudo entregarla. Estos son los que despiertan a los ingenieros de guardia.

Las comparaciones con «vs» que hacen tropezar a todo el mundo

401 frente a 403. El par que más se confunde. 401 Unauthorized significa «no te has autenticado, intenta iniciar sesión» (el nombre es técnicamente engañoso: tiene que ver con la autenticación, no con la autorización). 403 Forbidden significa «estás autenticado, pero no se te permite hacer esto»: tus credenciales son válidas, pero no conceden acceso a este recurso. Un uso indebido común: devolver 403 para peticiones no autenticadas cuando lo correcto es 401 con una cabecera WWW-Authenticate.

301 frente a 302 frente a 307 frente a 308. Dos ejes, permanente frente a temporal, y el comportamiento de conservación del método:

Si rediriges peticiones GET con fines de SEO, 301 es la opción convencional. Si rediriges peticiones POST o PUT y quieres que se conserve el método, necesitas 307 o 308.

400 frente a 422. 400 Bad Request es para peticiones con la sintaxis mal formada: JSON no válido, falta de cabeceras obligatorias, parámetros de consulta mal formados. 422 Unprocessable Entity (originalmente un código de WebDAV, ampliamente adoptado por las API REST) es para peticiones con la sintaxis válida pero con problemas semánticos: el JSON se analiza correctamente, pero los valores no superan la validación de negocio (cantidad negativa en un pedido, correo electrónico ya en uso). Muchas API usan ambos.

502 frente a 503 frente a 504. Tres modos de fallo del servidor de origen distintos:

• 502 Bad Gateway: el proxy o la pasarela recibió una respuesta no válida del servidor de origen.
• 503 Service Unavailable: el servidor está sobrecargado o en mantenimiento. A menudo se combina con una cabecera Retry-After.
• 504 Gateway Timeout: el servidor de origen no respondió a tiempo.

404 frente a 410. 404 Not Found es «no sabemos si esto existe o no». 410 Gone es «esto existía antes, se ha eliminado de forma permanente». Impacto en el SEO: Google trata 410 como una señal más fuerte de que el contenido no está disponible de forma permanente y lo elimina del índice más rápido que en el caso de 404.

Convenciones de las API REST

Las API REST modernas convergieron en un conjunto de convenciones bastante coherente sobre qué códigos de estado significan para cada acción:

Implicaciones para el SEO

• 200 OK: Google indexa la página con normalidad.
• 301 Moved Permanently: Google actualiza la URL indexada a la nueva y transfiere las señales de posicionamiento.
• 302 Found / 307 Temporary Redirect: Google mantiene indexada la URL original; el posicionamiento se queda con la original.
• 308 Permanent Redirect: Google lo trata como un 301: el posicionamiento se transfiere.
• 304 Not Modified: lo usa Googlebot para las peticiones condicionales; indica que el contenido en caché puede reutilizarse.
• 404 Not Found: Google elimina la URL de su índice tras unos cuantos rastreos.
• 410 Gone: Google elimina la URL más rápido que con 404; la señal más fuerte de «desaparecido de forma permanente».
• 503 Service Unavailable con Retry-After: le dice a Googlebot que vuelva más tarde. Úsalo durante las ventanas de mantenimiento; evita usar 503 para errores reales (Google interpreta los 503 sostenidos como instrucciones para no rastrear).
• 5xx sostenido: Google reduce la frecuencia de rastreo y, con el tiempo, puede llegar a eliminar la URL del índice por completo.

Códigos famosos & culturales

• 418 I'm a teapot: una inocentada del RFC 2324 (Hyper Text Coffee Pot Control Protocol, 1 de abril de 1998). Cuando el IETF propuso eliminarlo de la especificación en 2017, la campaña «Save 418» consiguió mantenerlo en vigor. Algunas API lo usan como un marcador de «esto no es real»; por lo demás, es inofensivo.
• 451 Unavailable For Legal Reasons: RFC 7725 (2015), llamado así por Fahrenheit 451 de Ray Bradbury. Se devuelve cuando el contenido se censura por orden judicial o a petición del gobierno.
• La serie 520-527 de Cloudflare: no estándar, usada por Cloudflare para indicar fallos concretos de conexión con el servidor de origen. Común cuando un sitio detrás de Cloudflare tiene problemas.
• El 444 No Response de Nginx: específico de Nginx, se devuelve cuando el servidor cierra la conexión sin enviar ninguna respuesta.
• El histórico 420 Enhance Your Calm de Twitter: un código de límite de peticiones ya retirado que usaba la antigua API de Twitter; sustituido por el estándar 429.

Errores frecuentes

1. Usar 200 OK para errores con un cuerpo de error. Devolver {"error": "not found"} con un estado 200 confunde a todas las capas de caché, herramientas de monitorización y SDK de cliente. Usa el código de estado correcto.
2. Devolver 403 para peticiones no autenticadas. El código correcto es 401 con una cabecera WWW-Authenticate.
3. Usar 302 cuando quieres decir 301. Si el cambio es permanente, los motores de búsqueda necesitan el 301 para transferir el posicionamiento. 302 mantiene indexada la URL antigua.
4. Usar 301 o 302 para redirecciones POST/PUT. Históricamente, estos permitían a los clientes cambiar el método a GET. 307 y 308 conservan estrictamente el método original.
5. Devolver 500 cuando se quiere decir 503. Si el servidor está sobrecargado o en mantenimiento, 503 con Retry-After es la señal correcta, tanto para los clientes como para Googlebot.
6. Usar 404 para páginas eliminadas de forma permanente. 410 Gone es la señal más fuerte y se elimina de los índices de los motores de búsqueda más rápido.
7. Olvidar la cabecera Location en las respuestas 201 y 3xx. La cabecera Location es lo que le indica al cliente dónde reside el nuevo recurso o a dónde redirigir. Sin ella, los clientes no pueden navegar.

Más preguntas frecuentes

¿Cuándo debería devolver 422 en lugar de 400?

400 Bad Request significa que la propia petición está mal formada: JSON no válido, falta de cabeceras obligatorias, parámetros de consulta mal formados. 422 Unprocessable Entity significa que la petición está bien formada pero contiene errores semánticos que impiden su procesamiento: un campo de cantidad con un número negativo, una dirección de correo electrónico que ya está en uso, una fecha en el pasado para un campo que solo admite fechas futuras. Las convenciones modernas de las API REST convergieron en esta división, y la mayoría de las grandes API (GitHub, Stripe, Twilio) usan 422 para los errores de validación.

¿Por qué Cloudflare a veces devuelve 520, 521, 522…?

Los códigos 520-527 son específicos de Cloudflare y señalan distintas formas en que su red perimetral no pudo alcanzar tu servidor de origen. 520 es el genérico «el servidor web devolvió un error desconocido»; 521 significa que tu origen rechazó la conexión; 522 es un tiempo de espera de conexión con tu origen agotado; 524 significa que tu origen tardó demasiado en responder. No están en el registro de IANA, pero se encuentran con frecuencia cuando los sitios detrás de Cloudflare tienen problemas de backend.

¿Mi navegador me mostrará qué código devolvió mi API?

Sí: abre las DevTools → la pestaña Red, haz clic en la petición y mira la columna «Estado». Los navegadores también muestran páginas genéricas para algunos códigos (el juego del dinosaurio en los fallos de conexión de Chrome, las páginas estándar 404 / 500); pero el código numérico real siempre está en la respuesta.

¿Qué es 103 Early Hints?

Un código 1xx relativamente nuevo (RFC 8297, 2017) que permite al servidor enviar cabeceras Link: rel=preload antes de que la respuesta completa esté lista, indicando al navegador que empiece a obtener pronto los recursos críticos (CSS, fuentes, imágenes). Ahora es compatible con Chrome y lo implementan Cloudflare, Fastly y otras CDN como una optimización del rendimiento.

¿Puedo inventarme mi propio código de estado?

Técnicamente sí (HTTP permite cualquier código de 3 dígitos en el rango 100-599). En la práctica, no: los clientes, los proxies y las cachés tratan los códigos desconocidos por su primer dígito (así, 4xx = error del cliente de forma genérica, 5xx = error del servidor). Algunos proveedores lo hacen (los 520 de Cloudflare, el 444 de Nginx), pero, a menos que controles ambos extremos de la conexión, cíñete al registro de IANA. Inventar un 299 no romperá nada, pero tampoco comunicará nada.

¿Por qué el «código de estado» se llama «estado» y no «código de error»?

Porque la mayoría no son errores. 200 OK es el código de estado más devuelto del mundo: significa «todo salió bien». Los códigos comunican el estado de la petición: éxito, redirección, error del cliente, error del servidor. Llamarlos «códigos de error» sesga hacia los casos negativos que se registran y se notan; los códigos de éxito hacen su trabajo en silencio cada microsegundo.