Buscador de códigos de estado HTTP

Un código de estado es el veredicto del servidor sobre una petición resumido en un solo número, y suele ser el camino más rápido hacia la causa de un fallo. Te dice si debes mirar la petición que enviaste, la aplicación que la procesó o algo que se interpone entre ambas. La herramienta de arriba convierte ese número en esa respuesta.

Cómo funciona

Escribe un código (503), su comienzo (40 muestra del 400 al 409) o parte de un nombre (timeout, gateway), o elige una clase con los botones. Haz clic en cualquier entrada para ver qué significa. En los códigos que más aparecen al depurar, como 401, 404, 429, 500 y del 502 al 504, el panel añade qué suele provocarlos, cómo solucionarlos y qué códigos relacionados conviene revisar a continuación. Cada entrada indica la RFC que la define, para que puedas acudir a la fuente cuando un detalle importe.

La lista cubre todas las entradas permanentes del registro de códigos de estado HTTP de la IANA, incluido el 418, que el registro deja reservado porque la RFC de broma lo hizo demasiado popular como para reasignarlo. Nada de lo que escribes sale de tu navegador.

Lo primero: encontrar el código de estado

Las páginas de error suelen esconder el número real tras un mensaje amable, así que léelo en la propia respuesta:

• Navegador. Abre las herramientas para desarrolladores, ve al panel Red (Network) y recarga. Cada petición muestra su estado. En Chrome, filtra con status-code:500 u ordena la columna para agrupar los fallos.
• Terminal. curl -i imprime la línea de estado y las cabeceras antes del cuerpo. Para obtener solo el número, algo muy útil en scripts y health checks, descarta el cuerpo:

curl -s -o /dev/null -w '%{http_code}\n' https://example.com/api/orders

curl -I es tentador, pero envía una petición HEAD, y algunos servidores no responden a HEAD igual que a GET. Cuando no coincidan, fíate del método que usa realmente tu aplicación.

Un orden de diagnóstico que ahorra tiempo

Empieza por el primer dígito. Un 4xx significa que el servidor cree que el problema está en la petición, así que revisa la URL, el método, las credenciales y el cuerpo antes de tocar el servidor. Un 5xx significa que el servidor ha fallado en algo que debería haber gestionado, y la explicación está en sus logs, no en la respuesta.

Después, pregúntate quién lo ha generado. Un 502 o un 504 rara vez lo escribe tu aplicación. Viene del proxy, del balanceador de carga o de la CDN que tiene delante, e indica que la aplicación nunca respondió como debía. La cabecera Server y el estilo de la página de error suelen delatar la capa responsable. Reinicia o escala el servicio upstream, y revisa el timeout del proxy, antes de ponerte a buscar en el código de la aplicación.

Atento a los códigos que no están en el registro. Algunas piezas de infraestructura se inventan los suyos. Nginx registra un 499 cuando el cliente colgó antes de que la respuesta estuviera lista, y Cloudflare devuelve del 520 al 526 ante problemas de conexión o de TLS con el origen. La herramienta los marca como desconocidos, y esa es precisamente la pista: consulta la documentación de ese proveedor, no la especificación HTTP.

Reintentar sin riesgos

No todos los fallos merecen un reintento, ni todas las peticiones pueden repetirse sin peligro:

• 429 y 503 son una invitación a volver más tarde. Si la respuesta incluye Retry-After, espera al menos ese tiempo. Si no, aplica un backoff exponencial con jitter para que una flota de clientes no reintente al unísono.
• 502 y 504 suelen ser transitorios, pero reintenta automáticamente solo si el método es idempotente (GET, HEAD, PUT, DELETE). Puede que un POST que agotó el tiempo ya haya creado el pedido, así que reintentarlo a ciegas podría crearlo dos veces. Las claves de idempotencia existen justo para ese caso.
• La mayoría de los demás 4xx fallarán exactamente igual en cada intento. Reintentar un 400, un 403 o un 422 solo añade carga. Corrige la petición.

Para saber más

Códigos de estado HTTP: referencia completa explica cada clase a fondo, incluida la semántica de las redirecciones y de la caché, y las parejas que es fácil confundir. Si estás eligiendo los códigos de tu propia API en lugar de descifrar los de otra, lee Diseño de APIs REST. Cuando un 401 tiene que ver con un bearer token, el decodificador de JWT te muestra si ha caducado o si apunta a la audiencia equivocada, y el codificador de URL detecta las query strings mal escapadas que hay detrás de muchos 400.