¿Qué significa un 504 Gateway Timeout? Y de quién es la culpa

Un 504 Gateway Timeout significa que un servidor intermedio le pidió algo a otro servidor y se cansó de esperar. La página que querías existe. La máquina que la habría construido no respondió a tiempo, y la máquina que tiene delante dejó de aguantar la puerta abierta.

Si eres visitante: no es tu ordenador, ni tu navegador, ni tu conexión. Todo código de error que empieza por 5 es el propio sitio informando de un problema suyo. Vaciar la caché no ayudará, y probar otro navegador tampoco.

La foto de los dos servidores

Casi ninguna web es una sola máquina. Una petición llega normalmente a algo que está delante - un balanceador de carga, un proxy inverso, un borde de CDN - y esa cosa la pasa hacia atrás a lo que de verdad ejecuta la aplicación, y luego te devuelve la respuesta.

Un 504 es el informe de la máquina de delante sobre la de detrás: pregunté, esperé, no llegó nada, aquí tienes un código de estado para que no te quedes mirando una pestaña en blanco. La aplicación del sitio nunca tuvo ocasión de decirte nada, y por eso una página de 504 suele parecer genérica en vez de parecerse al sitio que la rodea.

Eso explica también los tiempos. Un 504 suele llegar tras una pausa larga - diez segundos, treinta, sesenta - porque la pausa es la cuestión. Algo seguía intentándolo.

504 frente a 502, que se confunden constantemente

Vienen del mismo sitio y significan cosas distintas, y saber cuál de los dos tienes acota bastante la causa.

502 Bad Gateway

El servidor de destino respondió, y la respuesta era inservible - una conexión rechazada, un proceso caído, basura en el cable. Suele ser rápido

504 Gateway Timeout

El servidor de destino no respondió en absoluto dentro del tiempo permitido. Suele ser lento, y el retraso antes del error es en sí mismo una pista

A grandes rasgos: 502 es “dijo algo mal”, 504 es “todavía no ha dicho nada”. Un 502 apunta a que algo está roto o caído; un 504 apunta a que algo está lento, atascado o sobrecargado.

Un matiz que conviene conocer, porque la mayoría de los artículos lo pasan por alto: algunos proveedores usan sus propios códigos para esto. Cloudflare devuelve 524 cuando tu origen acepta una conexión y luego tarda demasiado en responder, que es la misma historia contada desde otra capa. Si estás detrás de un CDN, el número que recibes puede ser el suyo y no el estándar.

Si eres el visitante

Hay muy poco que hacer, y esa es la respuesta honesta más que una respuesta corta.

Espera un minuto y recarga. Un 504 suele ser pasajero - una consulta lenta, un proceso reiniciándose, un pico de tráfico. Si persiste, mira si el servicio tiene una página de estado o si alguien más lo está reportando, porque el fallo está en su lado y solo ellos pueden arreglarlo.

Lo único de verdad útil que puedes hacer es contárselo, con detalle suficiente para que lo encuentren. Qué página, a qué hora y qué estabas haciendo. Un 504 en un pago a las 14:32 es algo que un ingeniero puede ir a buscar en un log; “vuestra web no va” no lo es.

Si el sitio es tuyo

Cuatro causas explican la mayoría, más o menos en este orden.

• Una cosa lenta. Una consulta a la base de datos sin índice, una API externa que llamas mientras el usuario espera, un informe que ha crecido más allá del tamaño para el que se diseñó. La petición no está atascada, solo es más lenta que la paciencia del proxy.
• Un tiempo de espera por debajo de la realidad. Nginx usa por defecto sesenta segundos para una lectura a través del proxy. Si tu petición legítima más lenta tarda noventa, servirás 504 a la gente que usa la función que más importa.
• Workers agotados. Todos los procesos de la aplicación están ocupados, así que las peticiones nuevas hacen cola detrás y no llegan siquiera al código. Este llega a rachas y parece que el sitio se cae entero, porque en la práctica es lo que pasa.
• La ruta de red. Un grupo de seguridad, un cambio de DNS, un servicio que se ha movido. Menos común, y normalmente total en vez de intermitente.

Averigua qué capa lo emitió antes de cambiar nada. El propio log de acceso del proxy registra el estado que devolvió y cuánto esperó; el log de la aplicación mostrará o bien una petición que tardó ese tiempo o bien nada en absoluto en ese momento. Esos dos casos tienen arreglos opuestos, y adivinar entre ellos es como la gente acaba subiendo un tiempo de espera que nunca fue el problema.

Subir el tiempo de espera es la jugada tentadora y por sí sola suele ser equivocada. Convierte un fallo rápido en uno lento y mueve la cola a otro sitio. Es la jugada correcta solo cuando sabes que el trabajo tarda legítimamente eso y no se puede hacer asíncrono.

Por qué luego cuesta tanto perseguirlos

Un 504 es un instante. Para cuando alguien lo menciona, la consulta lenta ha terminado, los workers se han vaciado, el pico ha pasado, y la página carga perfectamente cuando lo intentas.

Así que el reporte llega como “antes estaba roto” y no hay nada que mirar. Lo que lo haría localizable es lo que el navegador vio en su momento: qué petición agotó el tiempo, contra qué host, cuánto esperó y qué más de la página había fallado ya. Eso está en el panel de red mientras ocurre y desaparece en cuanto se cierra la pestaña.

Ese es el argumento para capturarlo en el momento en vez de describirlo después - un archivo HAR es la forma habitual de hacerlo a mano, y es exactamente lo que lleva el registro de red de un reporte de error. La misma evidencia responde a la otra pregunta que conviene hacerse pronto, que es si el tiempo de espera fue tu servicio o el de otro: la columna del host dice cuál.

En un párrafo

Un 504 significa que el servidor de delante preguntó al de detrás y se le acabó la paciencia. Es problema del sitio y no tuyo, normalmente quiere decir lento más que roto, y se distingue de un 502 por la pausa previa. Si el sitio es tuyo, averigua qué capa agotó el tiempo antes de tocar ningún ajuste de tiempo de espera, porque el log que no registró nada y el log que registró noventa segundos te están contando dos historias distintas.