Error 504 en WordPress: ¿hosting o sitio web?

#¿Qué significa el error 504 en WordPress?

MDN, siguiendo el RFC 9110, define el 504 como la situación en la que un servidor que actúa como pasarela o proxy “did not get a response in time from the upstream server”. Es distinto del 502 Bad Gateway: allí la respuesta llegó, pero no era válida. En el 504 no llegó nada.

En un hosting WordPress típico la cadena es esta: navegador, opcionalmente una CDN, nginx, PHP-FPM, la base de datos y, en su caso, una caché de objetos. El código 504 lo genera el eslabón que estaba esperando, y eso ya indica dónde buscar. Si nginx espera a PHP, el problema está en PHP, en la base de datos o en la cola de PHP. Si espera la CDN, el problema está en el servidor de origen.

La documentación de MDN advierte además de que las causas son muchas y de que la reparación suele requerir un análisis por parte del administrador del servidor. Por eso aquí no hay una corrección mágica, sino un orden de comprobaciones.

#¿El 504 es culpa del hosting o del sitio?

Lo decide el alcance del error. La tabla siguiente es un atajo para decidir, no una sentencia.

La responsabilidad del hosting empieza donde los límites (número de workers, memoria, CPU) son demasiado pequeños para el tráfico normal del sitio. La responsabilidad del sitio empieza donde una sola petición hace tanto trabajo que bloquea un worker durante decenas de segundos. En la práctica suelen darse las dos cosas a la vez: las peticiones lentas ocupan a los workers y un pool pequeño no tiene margen.

#¿Cómo comprobar dónde se atascó la petición?

Empiece por tres sitios, en este orden.

1. Log de errores del servidor web de la hora del fallo. En nginx, una entrada upstream timed out confirma que el servidor esperaba a PHP.
2. Log de PHP-FPM. El aviso de que se alcanzó pm.max_children significa que el pool estaba lleno y las peticiones siguientes esperaban en cola. La opción pm.max_children, según la documentación de PHP, fija el límite de peticiones simultáneas que atiende el pool.
3. Log de WordPress. Ponga en wp-config.php WP_DEBUG en true, WP_DEBUG_LOG en true y WP_DEBUG_DISPLAY en false. Los errores irán a wp-content/debug.log en lugar de a la pantalla. Así lo describe la documentación de WordPress. Desactive el debug al terminar el diagnóstico.

Si el hosting da acceso al slowlog de PHP-FPM, configure request_slowlog_timeout y PHP guardará el backtrace de las peticiones que duren más que el límite. Por defecto la opción está desactivada (valor 0). El backtrace muestra en qué función del plugin o del tema se quedó esperando PHP.

En un hosting compartido a menudo no hay acceso a estos logs. Entonces, lo primero que hay que pedir al soporte es el acceso a ellos y a las métricas del pool de PHP, junto con la hora del fallo y la dirección que devolvió el 504.

#¿Por qué un pool de PHP-FPM demasiado pequeño provoca un 504?

Cada petición dinámica ocupa un worker de PHP-FPM hasta el final de la respuesta. Cuando todos los workers están ocupados, las peticiones nuevas esperan. Si esperan más que el límite del proxy, el visitante ve un 504.

El fastcgi_read_timeout por defecto de nginx es de 60 segundos, y la documentación de nginx aclara que el límite se cuenta entre dos lecturas consecutivas del servidor FastCGI, no para toda la respuesta. En los hostings gestionados el valor puede ser otro, así que no dé por hecho que en el suyo son justo 60 segundos.

Subir pm.max_children solo ayuda si el servidor tiene memoria para ello. Cada worker de WordPress con varios plugins ocupa una parte considerable, de modo que un valor demasiado alto termina agotando la RAM y matando procesos, un estado peor que la cola. La configuración del pool es tarea de un administrador que vea el consumo de memoria.

#¿Cómo provocan un 504 las consultas lentas y las opciones autocargadas?

Cuando el 504 afecta a todo el sitio y el pool no está lleno por el tráfico, revise la base de datos. La documentación de WordPress señala que WordPress repite muchas consultas en cada petición y que las opciones marcadas como autoload se cargan en cada visita. Recomienda mantenerlas por debajo de 800 KB, y las recomendaciones completas están en la guía de optimización. Un plugin que guarda datos grandes en wp_options con autoload los mete en cada petición. El tamaño del autoload se comprueba con una consulta SQL sobre la columna autoload de la tabla de opciones.

Para localizar consultas lentas sirve la constante SAVEQUERIES. Guarda cada consulta, su tiempo de ejecución y la función que la lanzó en $wpdb->queries. Cuesta rendimiento, así que actívela un rato y, si es posible, en staging.

#¿Cuándo provocan un 504 la caché de objetos y Redis?

Una caché de objetos persistente reduce el número de consultas a la base de datos y normalmente acelera el sitio. Pero necesita un servidor de caché que funcione y el archivo drop-in wp-content/object-cache.php.

El fallo funciona al revés cuando ese archivo existe y el servidor Redis no responde. Cada petición intenta entonces conectarse a la caché, espera al timeout de conexión y solo después continúa o se rinde. El síntoma es un 504 justo después de un reinicio o de una caída del servicio de caché en el hosting, aunque el código del sitio no haya cambiado.

La prueba es sencilla: cambie el nombre de object-cache.php. Si el 504 desaparece, el culpable es la caché y no WordPress. Restaure el archivo solo después de reparar el servicio.

#¿Cómo provocan un 504 WP-Cron, admin-ajax y las API externas?

Conviene revisar por separado tres fuentes de peticiones lentas aisladas.

• WP-Cron. La documentación de WordPress explica que WP-Cron se ejecuta cuando alguien entra en el sitio, no como un proceso permanente. Las tareas pesadas y atrasadas (copias de seguridad, importaciones, envíos) pueden, por tanto, cargar la petición normal de un visitante. Trasladar las llamadas al cron del sistema del hosting descarga el front.
• admin-ajax.php. Los plugins envían aquí peticiones desde el panel y desde el front. Si el 504 aparece justo aquí, busque el plugin que hace una operación pesada en segundo plano.
• API externas. Un plugin que espera a un sistema externo lento (pagos, ERP, envíos) retiene al worker mientras el otro sistema tarda en responder. Si ese plugin no tiene un timeout propio y corto, la caída ajena se convierte en su 504.

#¿En qué se diferencia el 504 del 502 y del 524?

• 502 Bad Gateway: el servidor situado detrás del proxy respondió, pero la respuesta no era válida. A menudo es un proceso de PHP-FPM caído.
• 504 Gateway Timeout: ausencia de respuesta a tiempo. Lo más frecuente es una sobrecarga o una petición lenta.
• 524: código de Cloudflare. La documentación de Cloudflare indica que aparece cuando el servidor de origen no responde en los 125 segundos por defecto. Cloudflare aconseja pedir al hosting que revise los procesos largos y la sobrecarga, y mover las operaciones grandes a un canal sin proxy.

Detrás de una CDN puede, por tanto, ver dos códigos distintos para la misma causa, según qué eslabón perdió antes la paciencia.

#¿Cuándo subir el timeout y cuándo no?

Subir fastcgi_read_timeout o el límite de tiempo de PHP está justificado para una operación aislada y deliberadamente larga, por ejemplo una importación manual. Para un sitio que muestra 504 a los visitantes es enmascarar el problema: la petición lenta sigue ocupando un worker, solo que durante más tiempo, y el pool se llena más rápido.

PHP-FPM tiene otro fusible, request_terminate_timeout. La documentación lo describe como el límite tras el cual se mata el proceso que atiende la petición, y da como valor por defecto 0, es decir, desactivado. Bien ajustado, protege al pool de un único script colgado.

#¿Cómo arreglar un 504 paso a paso?

1. Determine el alcance: todo el sitio, una sola dirección o solo wp-admin.
2. Lea los logs del servidor y de PHP-FPM de la hora del fallo.
3. Active debug.log y reproduzca el error.
4. Desactive los plugins (con WP-CLI o renombrando el directorio), después vaya activándolos de uno en uno y mida el tiempo de respuesta.
5. Si existe object-cache.php, desactívelo como prueba.
6. Revise las opciones autocargadas y las tareas atrasadas de WP-Cron.
7. Solo al final, plantéese aumentar el pool o los timeouts, junto con el administrador del hosting.

Si el 504 apareció justo después de una actualización, consulte también la guía sobre cómo recuperar WordPress tras una actualización fallida.

#¿Cuándo es trabajo para un especialista?

Cuando los logs apuntan al pool de PHP-FPM, pero el hosting no da acceso a su configuración. Cuando el 504 vuelve tras cada reparación. Cuando la tienda pierde pedidos durante la caída. En una auditoría que deba separar el coste del hosting del coste del código, ayuda la optimización de la velocidad de WordPress. Si el sitio está caído ahora y se desconoce la causa, la salida es el servicio de reparación y soporte técnico de WordPress.