Помилка 502 Bad Gateway з’являється, коли проміжний сервер (шлюз або проксі) отримує некоректну чи порожню відповідь від сервера, що стоїть вище за ланцюгом. Це не збій вашого браузера чи інтернету — проблема лежить у взаємодії між серверами, і саме тому вона часто виглядає раптовою та незрозумілою.
Найчастіше її провокують падіння backend-процесів, перевантаження, неправильні налаштування upstream або тайм-аути. Для звичайного відвідувача достатньо кількох простих кроків, а для власника сайту потрібна системна діагностика логів і конфігурацій.
Нижче розібрано механізм виникнення, типові сценарії, покрокові дії для різних рівнів користувачів і способи запобігання повторним появам помилки.
Як саме працює механізм помилки 502
Коли ви відкриваєте сайт, запит рідко йде прямо до кінцевого сервера з контентом. Між браузером і origin-сервером майже завжди стоїть проксі, CDN, балансувальник навантаження або reverse-proxy на кшталт Nginx чи Apache. Саме цей проміжний вузол і називається gateway.
Gateway приймає ваш запит, пересилає його далі і чекає на відповідь. Якщо відповідь приходить у неправильному форматі, обривається на півдорозі або взагалі відсутня у вигляді валідного HTTP-повідомлення, gateway не може передати вам нормальну сторінку. Замість цього він повертає код 502. Важливо відрізняти його від 504 Gateway Timeout: при 504 backend просто не встиг відповісти вчасно, а при 502 він відповів, але відповідь виявилася непридатною.
З технічної точки зору «невалідна відповідь» включає кілька випадків: з’єднання відхилено (Connection refused), upstream передчасно закрив з’єднання, заголовки відповіді виявилися занадто великими для буферів проксі, або відповідь взагалі не відповідала синтаксису HTTP. Саме тому в логах Nginx найчастіше з’являються рядки на кшталт «upstream prematurely closed connection» або «connect() failed (111)».
Основні причини появи помилки 502
На практиці більшість випадків зводиться до кількох повторюваних сценаріїв. Перший і найпоширеніший — падіння або зупинка backend-процесу. PHP-FPM, Node.js-додаток, Gunicorn чи контейнер могли завершитися через вичерпання пам’яті, помилку в коді після деплою або звичайний OOM-kill. Gateway намагається підключитися до порту чи сокету, отримує відмову і видає 502.
Друга група причин — перевантаження. Коли всі worker-процеси зайняті, нові запити потрапляють у чергу і врешті-решт відкидаються. Третя — помилки конфігурації: неправильний шлях до Unix-сокету PHP-FPM, вказаний порт, на якому ніхто не слухає, або розбіжність між proxy_pass і реальним адресом додатку. Четверта — мережеві обмеження: файрвол, security group у хмарі чи SELinux блокують внутрішній трафік між проксі та backend.
Окремо варто згадати проблеми з DNS і SSL. Якщо gateway не може розв’язати ім’я upstream-сервера або сертифікат backend не підходить, з’єднання теж зривається з тією ж помилкою 502.
Покрокові дії для звичайного користувача
Якщо ви просто зайшли на сайт і побачили 502, почніть з найпростішого. Оновіть сторінку жорстким оновленням — Ctrl+F5 на Windows або Cmd+Shift+R на macOS. Багато 502 виникають на кілька секунд під час короткого збою і зникають самі.
Далі очистіть кеш і cookies браузера. Застарілі дані іноді змушують браузер повторно використовувати помилкову відповідь. Спробуйте режим інкогніто або інший браузер — це швидко покаже, чи проблема локальна. Якщо сайт відкривається з іншого пристрою чи мережі, справа, найімовірніше, у вашому DNS-кеші. На Windows виконайте команду ipconfig /flushdns, на macOS — dscacheutil -flushcache.
Перевірте, чи сайт взагалі працює для інших. Сервіси на кшталт isitdownrightnow.com дають швидку відповідь. Якщо помилка масова — залишається лише почекати, поки адміністратори усунуть причину.
Дії для власників сайтів і системних адміністраторів
Тут уже потрібен системний підхід. Першим кроком завжди дивіться логи проксі. У Nginx це /var/log/nginx/error.log. Рядок «connect() failed (111: Connection refused)» майже завжди означає, що backend не запущений або слухає інший порт. «upstream prematurely closed connection» вказує на те, що процес впав під час обробки запиту.
Далі перевірте, чи живий сам backend. Для PHP-FPM: systemctl status php8.2-fpm (версію підставте свою). Для Node.js — pm2 status або ss -tlnp | grep потрібний_порт. Якщо процес мертвий — перезапустіть його і одразу подивіться його власні логи, щоб зрозуміти причину падіння.
Переконайтеся, що конфігурація upstream збігається з реальністю. У Nginx перевірте fastcgi_pass або proxy_pass. Після змін обов’язково зробіть nginx -t і reload. Якщо використовуєте CDN (Cloudflare, Fastly), тимчасово вимкніть його або переведіть у режим «Development», щоб виключити проблеми на рівні edge.
У нашій практиці ми стикалися з випадком, коли після оновлення PHP сокет змінив ім’я, а в конфігурації Nginx залишився старий шлях. Сайт лежів майже годину, поки хтось не помітив розбіжність у логах.
Поширені помилки під час спроб виправлення
- Сліпе збільшення всіх тайм-аутів. Це лише маскує повільний backend і може призвести до накопичення зависших з’єднань. Спочатку знайдіть, чому запит обробляється довго.
- Перезапуск лише Nginx без перевірки backend. Проксі працює, а джерело проблеми — впалий PHP-FPM або Node-процес.
- Ігнорування логів і «лікування» навмання. Без точного повідомлення з error.log ви витрачаєте час на непотрібні зміни.
- Зміна DNS без очікування пропагації. Після переносу сайту 502 може триматися добу, поки кеші не оновляться.
- Вимкнення всіх плагінів і тем одразу без поетапної перевірки. Це ускладнює пошук конкретного винуватця.
Кожна з цих дій здається логічною, але без діагностики лише подовжує простій.
Чек-лист швидкої самоперевірки
- Чи оновлюється сторінка після жорсткого refresh?
- Чи відкривається сайт у режимі інкогніто або з іншого браузера?
- Чи працює сайт для інших користувачів (перевірка через isitdownrightnow)?
- Чи запущений backend-процес (systemctl status / pm2 status / ss -tlnp)?
- Чи є свіжі записи про upstream у error.log проксі?
- Чи збігається шлях до сокету або порт у конфігурації з реальним?
- Чи не блокує файрвол внутрішній трафік між проксі та backend?
- Чи не перевищують заголовки відповіді розмір буферів (proxy_buffer_size)?
Пройдіть список зверху вниз — у більшості випадків причина знаходиться на одному з перших п’яти пунктів.
Коли можна впоратися самому, а коли варто кликати фахівця
Якщо ви звичайний відвідувач і помилка зникла після оновлення чи очищення кешу — все гаразд. Якщо ж ви власник невеликого сайту на shared-хостингу і після перезапуску PHP-FPM через панель керування сайт ожив — теж можна обійтися власними силами.
Звертатися до спеціаліста варто, коли:
- помилка повторюється щодня або після кожного деплою;
- логи показують складні мережеві або SSL-проблеми;
- сайт працює на кластері, Kubernetes чи з кількома CDN-рівнями;
- після всіх очевидних кроків 502 залишається, а трафік критичний для бізнесу.
У таких випадках час простою коштує дорожче, ніж година роботи досвідченого DevOps.
Як зменшити ймовірність появи помилки 502 у майбутньому
Налаштуйте моніторинг процесів і ресурсів. Алерти на високий CPU, вичерпання пам’яті чи падіння PHP-FPM дозволяють реагувати до того, як користувачі побачать 502. Використовуйте graceful restart для додатків, щоб під час оновлень не обривати активні з’єднання.
Тримайте тайм-аути проксі трохи вищими за реальний P99 часу відповіді backend, але не робіть їх безкінечними. Регулярно перевіряйте конфігурацію після змін версій PHP чи фреймворків — шляхи до сокетів часто змінюються. І обов’язково майте резервний план масштабування: навіть найкращий сервер може не витримати раптового сплеску трафіку.
Помилка 502 — це не вирок, а сигнал, що в ланцюжку серверів щось пішло не так. Чим швидше ви навчитеся читати цей сигнал у логах і конфігураціях, тим рідше він перетворюватиметься на реальний простій.
