HTTP 502 Bad Gateway — код ответа, стандартизированный в RFC 9110, возвращаемый промежуточным сервером (reverse proxy, балансировщик нагрузки, CDN) когда upstream-сервер вернул неверный ответ или недоступен. Отличается от 503 (Service Unavailable): 502 — проблема с ответом бэкенда, 503 — сам промежуточный сервер перегружен или в maintenance.
Частые причины 502 в Nginx
Nginx как reverse proxy возвращает 502 при нескольких сценариях:
- PHP-FPM не запущен или упал — Nginx получает
connect() failed (111: Connection refused)при попытке подключиться к сокету PHP-FPM. Проверка:systemctl status php8.2-fpm. - PHP-FPM исчерпал пул воркеров — все
pm.max_childrenзаняты, новые запросы отклоняются. В error.log:upstream timed out ... while reading response header from upstream. - Upstream вернул невалидный HTTP-ответ — например, Python/Node.js приложение упало и ничего не вернуло, или вернуло мусор вместо HTTP.
- Превышен
proxy_read_timeout— upstream работает, но отвечает дольше заданного timeout (по умолчанию 60 с). В error.log:upstream timed out (110: Connection timed out). - Соединение с upstream разорвано — upstream аварийно завершился во время обработки запроса.
Диагностика 502
Быстрый чеклист при появлении 502:
tail -100 /var/log/nginx/error.log | grep -i upstream— сообщение укажет на конкретную причину.systemctl status php8.2-fpm— статус PHP-FPM.ss -tlnp | grep :9000— слушает ли PHP-FPM на нужном порту (илиls /var/run/php/php8.2-fpm.sockдля Unix-сокета).systemctl status nginx— может, Nginx сам завис.
502 vs 503 vs 504
| Код | Причина | Типичное решение |
|---|---|---|
| 502 Bad Gateway | Бэкенд недоступен или вернул невалидный ответ | Перезапустить PHP-FPM / приложение |
| 503 Service Unavailable | Сервер перегружен или на maintenance | Масштабировать, увеличить пул воркеров |
| 504 Gateway Timeout | Бэкенд не ответил за отведённое время | Увеличить timeout, оптимизировать запрос |
История
HTTP-коды состояния стандартизированы в RFC 1945 (HTTP/1.0, 1996). Класс 5xx означает ошибку на стороне сервера. Код 502 изначально предназначался для прокси-серверов при работе с диал-ап соединениями. С распространением reverse-proxy архитектур (Nginx, HAProxy, Cloudflare) в 2000-х годах 502 стал одним из наиболее часто встречаемых кодов в production.
Профилактика 502 на VPS
Для снижения вероятности 502 на VPS:
- Настроить автоматический перезапуск PHP-FPM через
Restart=alwaysв systemd unit-файле. При падении сервис поднимется через 5 секунд. - Увеличить
pm.max_childrenв PHP-FPM при постоянной очереди запросов. Формула: max_children = (доступная RAM для PHP) / (средний размер PHP-процесса). При 2 ГБ RAM и 50 МБ на процесс — max_children = 40. - Настроить мониторинг PHP-FPM через Prometheus php-fpm_exporter: метрика
phpfpm_active_processesу порога max_children — признак скорого 502. - Настроить
proxy_next_upstream error timeoutв Nginx для переключения на резервный upstream при 502. - Health-check upstream через Nginx Plus или HAProxy: автоматическое исключение упавшего backend из балансировки.
502 в контексте CDN и облачных сервисов
При использовании Cloudflare или другого CDN перед сервером пользователь видит страницу ошибки CDN с кодом 502, а не Nginx-страницу. Это означает, что CDN получил 502 от origin-сервера и не может достучаться до бэкенда. В Cloudflare это «Error 502: Bad Gateway» с кодом ray ID. Диагностика: прямое обращение к origin по IP (минуя CDN) поможет понять, отдаёт ли сервер 502 самостоятельно или только через прокси. Если сервер напрямую отвечает 200, проблема в конфигурации проксирования CDN.