Ошибка 502 Bad Gateway: что это и как исправить

Что значит ошибка 502 Bad Gateway

По RFC 9110 (раздел 15.6.3) код 502 Bad Gateway возвращает сервер, который действует как шлюз или прокси и получил недопустимый ответ от вышестоящего (upstream) сервера. На практике схема такая: посетитель обращается к nginx, nginx передаёт запрос приложению, а приложение недоступно, упало на середине ответа или ответило чем-то, что прокси не может разобрать.

Поэтому 502 почти всегда означает проблему «за» веб-сервером, а не в нём самом. Запрос посетителя был нормальным, и перенаправление ссылки или смена браузера здесь не поможет.

502 и 504: как отличить

Разбор второго случая — на странице про ошибку 504 Gateway Timeout.

Что делать посетителю

1. Обновите страницу через 1–2 минуты: если приложение просто перезапускалось после обновления, ошибка исчезнет.
2. Проверьте, виден ли сайт другим людям и из другой сети (мобильный интернет вместо Wi-Fi). Это быстро отделяет проблему сайта от проблемы вашего подключения.
3. Очистите кэш и куки сайта, попробуйте режим инкогнито и другой браузер.
4. Отключите VPN или прокси. Если сайт стоит за CDN, часть узлов может работать с перебоями, и смена IP иногда меняет результат.
5. Если ошибка держится дольше часа, напишите владельцу сайта или в поддержку, указав время и адрес страницы.

Сообщение «Request failed with status code 502» в приложениях и сайтах на JavaScript значит то же самое: запрос ушёл на API, а шлюз перед ним получил плохой ответ. Пользователю остаётся повторить действие позже.

Как владельцу найти причину ошибки 502

Откройте журнал ошибок nginx (/var/log/nginx/error.log) и найдите строку на момент сбоя. В ней почти всегда прямо написано, что случилось с upstream.

PHP-FPM: перегруженный пул и перезапуски

В логе PHP-FPM (/var/log/php8.2-fpm.log) ищите предупреждение server reached pm.max_children setting. Оно говорит, что все процессы заняты и новые запросы встают в очередь или отбрасываются. Увеличьте pm.max_children в пределах доступной памяти (сколько в среднем занимает один процесс — смотрите в top или ps) и найдите тяжёлые запросы: если один скрипт занимает процесс на минуты, лимит исчерпается при любом размере пула.

# работает ли приложение и слушает ли нужный порт
systemctl status php8.2-fpm
ss -ltnp | grep -E ':3000|:9000'

# проверка конфигурации nginx и плавная перезагрузка
nginx -t && systemctl reload nginx

# 502 по адресам за последний лог
awk '$9 == 502 {print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head

Слишком большие заголовки ответа

Ошибка upstream sent too big header решается увеличением буфера под заголовки ответа. Для PHP-FPM это fastcgi_buffer_size, для проксирования на Node.js, Next.js и т. п. — proxy_buffer_size. Но сначала выясните, почему заголовки стали огромными: часто это разросшиеся куки или ошибка в приложении, которая выставляет Set-Cookie на каждый запрос.

# PHP через PHP-FPM
location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_buffer_size 16k;
    fastcgi_buffers 16 16k;
}

# приложение на Node.js / Next.js
location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffer_size 16k;
    proxy_buffers 8 16k;
}

Приложение на Next.js за nginx разобрано в руководстве по Next.js, общие настройки сервера — в руководстве по nginx.

Если сайт стоит за CDN или балансировщиком

502 может приходить от CDN, а не от вашего сервера: сеть доставки не смогла получить корректный ответ от исходного сервера. Обратитесь к исходному серверу напрямую (по его IP с нужным заголовком Host), и если там всё нормально, разбирайтесь с настройками CDN и фаервола на исходном сервере, который мог заблокировать адреса CDN.

Как проверить код ответа

Проверьте проблемный адрес инструментом ниже. Он покажет итоговый код и цепочку редиректов, а значит, и то, на каком шаге появляется 502: на самом URL или уже после перенаправления.

Ошибка 502 и индексация

• Для Яндекса и Google 502 — временная серверная ошибка. Единичные ответы 502 индексацию не ломают: роботы вернутся позже.
• При повторяющихся 5xx поисковые системы снижают частоту обхода, чтобы не перегружать сервер, и обновления страниц доходят до выдачи медленнее.
• Если страница долго отвечает 502, она может быть исключена из индекса. Точные сроки поисковики не называют, ориентируйтесь на то, что часы — это нормально, а дни — уже риск.
• Нестабильный 502 только на части URL (например, на самых тяжёлых страницах) труднее заметить: проверяйте не только главную, но и разные типы страниц.

Monitor404 следит за 404, но после аварий и откатов, когда часть страниц пропадает, он покажет, какие URL посетители теперь не находят.