Códigos de error HTTP, y cómo saber cuál está viendo en realidad

Todo error HTTP es una respuesta de una línea a una pregunta que nadie hizo en voz alta: ¿qué le pasó a mi petición? El número es toda la respuesta, y es deliberadamente escueto, así que casi todo el trabajo consiste en saber qué pregunta responde cada número.

Para eso está esta página. No una lista de los sesenta y pico códigos de estado, la mayoría de los cuales no verá nunca, sino la docena larga que llega de verdad a las personas, ordenada por lo que le dice sobre dónde estuvo el fallo.

La única división que importa

El primer dígito es la única parte del código que necesita recordar.

4xx

El servidor le entendió y se niega, o no pudo analizar lo que llegó. El problema está en la petición

5xx

La petición estaba bien. El servidor no logró producir una respuesta, o eligió no hacerlo

Todo lo demás se sigue de ahí. Un 4xx le manda a mirar lo que se envió: la URL, las cabeceras, el cuerpo, las credenciales. Un 5xx le manda a los logs del servidor y, si el servidor no es suyo, poco puede hacer más allá de informar bien.

La palabra “cliente” en “error del cliente” es donde la gente se pierde, así que conviene decirlo claro: el cliente no es usted. El cliente es el software que compuso la petición, y en un sitio moderno eso es casi siempre el propio JavaScript de la página. Un 4xx en el sitio de otro suele ser su bug con el nombre de usted puesto.

Los códigos 4xx con los que se va a encontrar

400 Bad Request es el servidor sin poder analizar en absoluto lo que llegó. Es el único de esta familia que trata de la forma de la petición y no del permiso o la existencia. Un cuerpo malformado, un content type que falta, una URL sin escapar. Hay una única versión que puede arreglar usted: un bloque de cookies que ha crecido demasiado, cosa que una ventana privada confirma en segundos.

401 y 403 son los dos que se intercambian constantemente. 401 significa que el servidor no sabe quién es usted y quiere credenciales. 403 significa que sabe exactamente quién es y la respuesta sigue siendo no. Mandar mejores credenciales arregla el primero y nunca arregla el segundo.

404 Not Found no necesita explicación, pero una cosa merece saberse: un 404 en una petición que la página hizo en segundo plano, y no en la barra de direcciones, casi siempre significa que un build o un despliegue perdió un archivo, no que alguien escribiera mal algo.

429 Too Many Requests es el único código de estado que trata de su comportamiento y no del servidor ni del recurso. Es además el único error en el que reintentar empeora las cosas, porque un reintento es otra petición que el limitador cuenta.

Los códigos 5xx, que parecen idénticos y significan cosas distintas

Los cuatro dicen “es cosa nuestra”, y distinguirlos decide dónde mira primero cualquiera.

500 Internal Server Error

La aplicación se ejecutó y su propio código falló. Una excepción no controlada. Respondió, y la respuesta fue un error que se hizo ella misma

502 Bad Gateway

Un servidor delantero recibió una respuesta inservible de la aplicación que tiene detrás. El fallo está entre dos servidores

503 Service Unavailable

Algo eligió no atenderle. Mantenimiento, capacidad, un limitador de tasa, o nada sano a lo que enrutar

504 Gateway Timeout

La aplicación nunca respondió a tiempo. El servidor delantero dejó de esperar

El atajo útil: un 500 es código que se rompe mientras corre, un 502 es un proxy que no consiguió una buena respuesta, un 504 es la aplicación siendo demasiado lenta, y un 503 es el único que suele ser deliberado. Esa última distinción importa más de lo que parece: un 503 a menudo lleva una cabecera Retry-After que dice exactamente cuándo volver, y casi nadie la lee.

Los errores que no son códigos de estado en absoluto

Algunos de los fallos más comunes no producen nunca un código de estado, y justamente por eso confunden. La petición no falló; nunca llegó a completarse.

TypeError: Failed to fetch es el error menos informativo de JavaScript. No hay estado que leer porque la petición nunca llegó lo bastante lejos como para tener uno.

Los errores CORS son el navegador negándose a entregar a su código una respuesta que sí llegó. El servidor respondió perfectamente; solo que no dijo que su origen estuviera permitido.

ERR_CONNECTION_REFUSED, RESET, CLOSED y TIMED_OUT ocurren por debajo de HTTP. Cada uno nombra hasta dónde llegó la conexión antes de morir, que es casi todo el diagnóstico gratis.

El contenido mixto es el navegador bloqueando un recurso inseguro en una página segura. No falló nada en la red; se aplicó una regla.

Leer uno que no es suyo

Si es visitante y no la persona que puede arreglarlo, tres comprobaciones separan la mayoría de los casos y llevan menos de un minuto.

Recargue una vez. Buena parte de los 500 y los 503 son un único mal momento. Si se aclara, no hay nada que perseguir.

Pruebe una ventana privada. Es la prueba para la familia de las cookies y las cabeceras: un 400 que desaparece en privado era un bloque de cookies demasiado grande, y uno que no desaparece nunca fue suyo.

Pruebe otra red. Un móvil con datos responde a la pregunta que plantea un limitador. Si el error le sigue a todas partes es su cuenta o el sitio; si desaparece, era la dirección desde la que venía. Es la misma pregunta que distinguir su bug de la caída de ellos, hecha deprisa.

Por qué el código por sí solo rara vez basta para arreglar nada

Cada error de arriba es un resumen con las pruebas quitadas. No es casualidad: un 500 es vago a propósito, porque la traza se queda en el servidor, y un 400 no le va a decir qué cabecera le ofendió. El código nombra la categoría y se calla el caso.

Así que “me salió un 500” es un informe que no le dice casi nada a un desarrollador y, para cuando alguien investiga, la petición que falló ya no está. Lo que cierra uno deprisa es la petición fallida en sí, su hora exacta, y qué estaba haciendo la persona.

El registro de red es donde un código de estado deja de ser una categoría y se vuelve un caso: la petición que se llevó el error, sus cabeceras y su cuerpo, y el minuto exacto, para que quien lo recoja pueda cruzarlo con un log del servidor en lugar de reproducirlo todo primero.

En un párrafo

El primer dígito es la división que importa: un 4xx significa que el problema está en la petición, un 5xx que el servidor no logró responder, y el “cliente” al que culpa un 4xx suele ser el propio JavaScript del sitio y no usted. Dentro de los 4xx, el 400 trata de la forma de la petición, el 401 y el 403 de identidad frente a permiso, y el 429 de con qué frecuencia pidió. Dentro de los 5xx, el 500 es código que se rompe, el 502 un proxy con una mala respuesta, el 504 nada que responda a tiempo, y el 503 el único que suele ser una decisión. Los errores sin código de estado alguno, como failed to fetch, CORS, ERR_CONNECTION_* o contenido mixto, son los que más confunden, porque la petición nunca se completó en vez de fallar. Sea cual sea el suyo, el código nombra la categoría y se calla el caso, así que capture la petición fallida mientras la tenga.