# Como corrigir o erro 504 Gateway Timeout

O erro 504 Gateway Timeout é um código HTTP que indica que um servidor intermediário (proxy ou gateway) esperou demais pela resposta do servidor de origem e desistiu. No WordPress, costuma vir de PHP-FPM travado, consulta de banco lenta ou timeout curto no Nginx.

## O que é o erro 504 no WordPress?

O 504 Gateway Timeout é um código de status HTTP em que um servidor agindo como gateway (Nginx na frente do PHP, ou o Cloudflare na frente do seu host) não recebeu a resposta do servidor de origem dentro do prazo e encerrou a conexão. Diferente do 502, em que a origem responde algo inválido, no 504 ela simplesmente não responde a tempo. No WordPress, o gargalo quase sempre está no PHP-FPM ou no MySQL demorando para concluir a requisição.

## Como identificar

- Mensagem "504 Gateway Timeout" ou "nginx/x.x.x 504 Gateway Time-out" no navegador.
- O erro aparece em páginas pesadas (importações, relatórios do WooCommerce, busca) e some em páginas leves.
- O site cai sob carga ou em horários de pico e volta sozinho quando o tráfego diminui.
- No error_log do Nginx aparece "upstream timed out (110: Connection timed out) while reading response header from upstream".

**Antes de começar:** Aumentar timeouts trata o sintoma, não a causa. Use os valores maiores para diagnosticar e volte a um limite saudável depois de resolver o gargalo real, para o servidor não acumular processos travados.

## Como prevenir

- Mantenha um plugin de cache de página ativo para reduzir o tempo de processamento sob carga
- Monitore consultas MySQL lentas e mantenha índices e a tabela wp_options enxutos
- Rode tarefas pesadas (backup, importação) via WP-CLI ou cron, fora do ciclo de requisição web

Erros relacionados

- [Como corrigir o erro 502 Bad Gateway no WordPress](https://full.services/wp-fixer/como-corrigir-erro-502-wordpress/)
- [Como corrigir o erro 503 Service Unavailable](https://full.services/wp-fixer/como-corrigir-erro-503-wordpress/)
- [Como corrigir o erro 500 Internal Server Error](https://full.services/wp-fixer/como-corrigir-erro-500-wordpress/)

## Causa

- PHP-FPM com worker travado ou esgotado, deixando a requisição sem resposta dentro do prazo do gateway.
- Consulta MySQL lenta (tabela sem índice, autoload inchado) que estoura o tempo de execução do PHP.
- Diretiva fastcgi_read_timeout do Nginx baixa demais para o tempo real de processamento da página.
- Plugin de backup, importação ou crawler rodando em processo longo que ultrapassa o limite do upstream.
- Cloudflare como proxy cortando a conexão em 100 segundos quando a origem demora além disso.

## Como resolver

1. Identifique a página que estoura o tempo: no error_log do Nginx, localize a linha "upstream timed out" e veja qual rota disparou o timeout. Isso separa um problema pontual (uma página pesada) de um gargalo geral do servidor.
2. Aumente o tempo de leitura do upstream no Nginx: no bloco do PHP-FPM do site, eleve o fastcgi_read_timeout e o proxy_read_timeout para 300s e recarregue o Nginx.

```
fastcgi_read_timeout 300;
proxy_read_timeout 300;
sudo nginx -t && sudo systemctl reload nginx
```

3. Aumente o tempo de execução do PHP: no php.ini do PHP-FPM, suba o max_execution_time e o request_terminate_timeout para acompanhar o novo limite do Nginx, e reinicie o serviço.

```
max_execution_time = 300
request_terminate_timeout = 300
sudo systemctl restart php8.2-fpm
```

4. Desative plugins para isolar o gargalo: via FTP, renomeie a pasta wp-content/plugins para testar se um plugin de backup, importação ou cache mal configurado está prolongando a requisição além do limite.
5. Otimize o banco de dados: limpe a tabela wp_options de entradas autoload inchadas e revise consultas lentas. Uma query sem índice é a causa silenciosa mais comum de 504 sob carga.

## Código

```nginx
# /etc/nginx/conf.d/seusite.conf - eleva o tempo de espera pelo PHP-FPM
location ~ .php$ {
    fastcgi_pass   unix:/run/php/php8.2-fpm.sock;
    fastcgi_index  index.php;
    include        fastcgi_params;
    # tempo que o Nginx espera o PHP-FPM responder antes de cortar com 504
    fastcgi_read_timeout    300;
    fastcgi_send_timeout    300;
    fastcgi_connect_timeout 60;
}
```

## Perguntas frequentes

### Qual a diferença entre erro 504 e erro 502?

No 502 Bad Gateway o servidor de origem responde algo inválido ao gateway. No 504 Gateway Timeout a origem não responde dentro do prazo e o gateway desiste de esperar. O 504 é sempre um problema de tempo: algo demorou demais.

### O erro 504 só aparece em algumas páginas. Por quê?

Essas páginas executam um processo mais pesado (importação, relatório, busca) que ultrapassa o tempo limite do gateway. Páginas leves respondem rápido e não estouram o timeout. Otimize a rota pesada ou aumente o tempo de execução.

### Aumentar o timeout do Nginx resolve de vez o 504?

Resolve o sintoma, não a causa. Se o gargalo for uma consulta lenta ou um plugin travando, o processo continua pesado. Use o timeout maior para diagnosticar e ataque a causa real: o banco, o plugin ou o PHP-FPM.

### O 504 veio do Cloudflare. O que muda?

O Cloudflare corta a conexão em cerca de 100 segundos quando a origem demora além disso e devolve o próprio 504. Verifique se o gargalo está no seu servidor: se a página responde direto no host mas dá 504 pelo Cloudflare, o tempo de origem está alto demais.

### Como sei qual processo está estourando o tempo?

Leia o error_log do Nginx procurando "upstream timed out" para ver a rota, e ative o log de consultas lentas do MySQL. Juntos eles apontam se o gargalo é PHP, banco ou um plugin específico.

### Reiniciar o PHP-FPM faz o 504 sumir?

Pode fazer sumir temporariamente, porque libera workers travados. Mas se a causa for uma página pesada ou uma query lenta, o erro volta na próxima vez que aquele processo rodar. Reiniciar é paliativo, não correção.

**Fonte:** [MDN Web Docs — 504 Gateway Timeout](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Status/504)