# 502 і 504 у Nginx: як знайти причину і полагодити сайт

> Чому Nginx повертає 502 Bad Gateway і 504 Gateway Timeout: розбір error.log, перевірка PHP-FPM і налаштування таймаутів proxy_pass.

## У чому різниця між 502 і 504

Обидві помилки означають, що Nginx не зміг отримати нормальну відповідь від бекенду — PHP-FPM, застосунку на Node.js чи іншого проксі-сервера. Але причини різні. 502 Bad Gateway означає, що бекенд відповів некоректно або з'єднання обірвалося. 504 Gateway Timeout означає, що бекенд не відповів за відведений час — він просто занадто довго думає.

Перший крок діагностики завжди один: відкрити `/var/log/nginx/error.log` і подивитися останні рядки за момент помилки.

## Як читати error.log при 502

Типові рядки при 502 і що вони означають:

| Рядок у логу | Причина |
| --- | --- |
| connect() failed (111: Connection refused) | PHP-FPM або бекенд не запущений або слухає інший сокет |
| recv() failed (104: Connection reset by peer) | Бекенд впав під час обробки запиту, найчастіше через нестачу пам'яті |
| upstream sent too big header | Заголовки відповіді бекенду перевищили буфер Nginx |

Перевірте, чи взагалі живий процес бекенду: `systemctl status php8.3-fpm`. Якщо сервіс впав, дивіться його власний лог: `/var/log/php8.3-fpm.log`.

## Як читати error.log при 504

Рядок `upstream timed out (110: Connection timed out) while reading response header from upstream` означає, що PHP-FPM прийняв запит, але не відповів за час, заданий у `proxy_read_timeout` чи `fastcgi_read_timeout`. Зазвичай так стається через довгий SQL-запит, зовнішній виклик API без таймауту або нестачу вільних воркерів PHP-FPM.

Перевірте чергу PHP-FPM: `systemctl status php8.3-fpm | grep -A2 active` і статус пулу через `fpm-status`, якщо він увімкнений у конфігурації.

## Як налаштувати таймаути правильно

Таймаути потрібно піднімати точково, лише для повільних маршрутів, а не глобально для всього сайту:

```
location /api/export/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_connect_timeout 5s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}
```

Для зв'язки з PHP-FPM аналогічні параметри називаються `fastcgi_connect_timeout`, `fastcgi_send_timeout` і `fastcgi_read_timeout`. Значення за замовчуванням — 60 секунд, піднімати вище 120 секунд майже ніколи не варто: це ознака того, що повільний код краще полагодити, а не маскувати таймаутом.

## Що перевірити на боці PHP-FPM

Часта причина і 502, і 504 — вичерпання пулу воркерів PHP-FPM. Перевірте параметри пулу в `/etc/php/8.3/fpm/pool.d/www.conf`:

- `pm.max_children` — замале значення створює чергу і таймаути під навантаженням
- `pm.max_requests` — періодичний перезапуск воркерів проти витоків пам'яті
- лог повільних запитів `slowlog` і `request_slowlog_timeout` — показує, який саме код гальмує

## Покроковий чек-лист діагностики

Порядок дій при появі 502 чи 504 на проді:

1. відкрити error.log і знайти точний рядок помилки за час інциденту
2. перевірити, чи живий процес бекенду: `systemctl status`
3. якщо бекенд живий — перевірити чергу та повільні запити через slowlog
4. якщо проблема в поодинокому повільному маршруті — підняти таймаут точково для нього
5. якщо проблема системна — збільшити pm.max\_children і додати моніторинг пам'яті

## Підсумок

502 означає, що бекенд відповів неправильно або впав, 504 — що він не встиг відповісти вчасно. В обох випадках рішення шукають не в Nginx, а в логах і налаштуваннях бекенду. Якщо помилки пов'язані саме зі зв'язкою Nginx і PHP, подивіться статтю [Nginx і PHP-FPM: сокети, пули і fastcgi\_params](https://www.zevshost.net/uk/kb/nginx-php-fpm-svyazka/), а базові принципи проксі розібрані у статті [reverse proxy на Nginx](https://www.zevshost.net/uk/kb/nginx-reverse-proxy/).

---

Джерело: https://www.zevshost.net/uk/kb/nginx-502-504-diagnostika/