502 Bad Gateway: що це означає, чому виникає та як усунути неполадки

Ключові слова

Цей короткий глосарій охоплює терміни інфраструктури, які найімовірніше викликатимуть плутанину під час детального пояснення.

Чому помилка 502 відчувається такою руйнівною

Ви виконуєте деплой, перезавантажуєте сайт, і домен відповідає миттєво — але не вашим застосунком. Або клієнт натискає «Оформити замовлення», сторінка завантажується, і транзакція обривається за суворим повідомленням 502 Bad Gateway. Саме це робить цю помилку такою стресовою: сайт доступний, але недостатньо справний, щоб завершити передачу.

502 перебуває в незручному проміжному стані. Це не схоже на повне зникнення, але й не поводиться як працюючий сервіс. Для розробників це може означати зламаний деплой або ланцюжок API. Для власників бізнесу — втрату довіри або переривання доходу. Для команд найгірше — це часто питання відповідальності: який рівень насправді відповідає за проблему?

Корисний підхід — не вгадувати. Спочатку визначте, що означає помилка. Потім визначте, де вона знаходиться в ланцюжку запитів. Потім усувайте збій логічно, по одній передачі за раз. Щойно ви побачите ланцюжок, помилка перестане здаватися випадковою.

Що насправді означає 502 Bad Gateway

Помилка 502 Bad Gateway зазвичай означає, що сервер, який діє як шлюз або proxy, не зміг використати відповідь, отриману від наступного рівня за ним. Простими словами: один сервер намагався передати ваш запит іншому серверу, і ця передача завершилася невдало настільки, що фронтальний сервер не зміг повернути нормальний результат.

📝 Примітка: Якщо upstream повертає власну валідну HTTP-помилку, proxy зазвичай передає цю помилку далі. Якщо застосунок повертає справжній 503 Service Unavailable, фронтальний рівень зазвичай має ретранслювати цей 503, а не генерувати 502. 502 означає, що сама відповідь була непридатною для використання. Якщо жодна придатна відповідь не надходить вчасно, це часто 504.

Найшвидший спосіб перестати неправильно читати 5xx-помилки — розділити їх за місцем збою та першим питанням, яке вони викликають:

⚠️ Попередження: Не об’єднуйте 500, 502, 503 та 504 в одну загальну категорію «сервер не працює». Вони вказують на різні форми збоїв, і це змінює те, що слід перевіряти в першу чергу.

Щойно це визначення стає зрозумілим, наступне питання стає набагато кориснішим: де в реальному стеку відбувається ця невдала передача?

Де виникає помилка в реальному ланцюжку запитів

Більшість сучасних запитів не йдуть напряму від браузера до застосунку. Вони проходять через рівні: браузер до CDN або edge, edge до reverse proxy або load balancer, proxy до процесу застосунку. Помилка 502 стає видимою в одній із цих точок передачі.

Спрощений ланцюжок запитів: Браузер → CDN/Edge → Reverse Proxy / Load Balancer → Застосунок / Процес

Reverse proxy приймає публічний запит і пересилає його всередину. Load balancer робить щось подібне, але може обирати між кількома справними цілями. В обох випадках фронтальний рівень маршрутизує запит, а не виконує бізнес-логіку самостійно.

Тут добре підходить аналогія з рецепцією. Уявіть proxy як рецепцію в офісній будівлі. Вона реєструє відвідувача, знаходить потрібний офіс і намагається передати відвідувача туди. Якщо офіс не відповідає, відповідає не по тій лінії або дає відповідь, яку рецепція не може використати, рецепція повертає збій. Саме тому видима помилка часто з’являється на рівні proxy, навіть якщо глибинна причина знаходиться деінде.

📝 Примітка: Proxy часто є посланцем збою, а не його першопричиною.

«Наступний сервер» за цією рецепцією може бути звичайним HTTP-сервісом на порту, слухачем застосунку, наприклад 127.0.0.1:3000, або локальним процесом на основі socket, наприклад PHP-FPM. Першопричина не обов’язково знаходиться в proxy. Невдалий деплой, збій робочого процесу застосунку або навіть збій бази даних можуть зламати backend настільки, що proxy — це просто місце, де з’являється 502.

Edge-сервіси додають ще один нюанс. CDN, наприклад Cloudflare, може пересилати 502 з боку origin з глибших рівнів вашого стеку, або може генерувати 502 самостійно, коли передача від edge до origin зазнає невдачі. Саме тому «хто повернув цю помилку?» — це перше практичне питання, а не другорядне.

Чому виникають помилки 502: основні категорії збоїв

Щойно ви перестаєте сприймати 502 як одну загадкову подію, картина причин стає набагато простішою для управління. Більшість інцидентів вписуються в три повторювані категорії: upstream недоступний, сама передача налаштована неправильно, або відповідь повертається у формі, яку шлюз не може використати.

Перша категорія — очевидна: upstream відсутній у придатному стані. Можливо, застосунок впав після деплою. Можливо, сервіс так і не перезапустився. Можливо, пул PHP-FPM завершив роботу, або ціль була позначена як нездорова і виключена з ротації. Це класичний сценарій «сервіс не працює», але це лише один зріз картини 502.

Друга категорія — невідповідність передачі. Тут обидва рівні можуть працювати, але вони не погоджуються щодо того, як досягти один одного. Proxy може вказувати на неправильний порт. Ім’я хоста може розв’язуватися неправильно. Брандмауер може блокувати шлях. Один рівень може очікувати HTTPS, тоді як наступний підтримує лише звичайний HTTP. Шлях socket міг змінитися. У таких випадках застосунок може бути справним, але з’єднання між рівнями все одно зламане.

Третя категорія складніша: upstream відповідає, але не так, щоб шлюз міг це використати. Ціль може скинути TCP-з’єднання, закрити його надто рано, надіслати неправильно сформовані або надмірно великі заголовки, або повернути неповний вивід під навантаженням. Застосунок не просто «вимкнений»; він відповідає настільки погано, що шлюз відхиляє отримане.

Це також пояснює, чому 502 — це не просто історія про тайм-аути. Деякі випадки тайм-ауту стають 504 Gateway Timeout, а не 502. Cloudflare може генерувати 502 на рівні edge, коли порушується з’єднання з origin або стиснення. Load balancer може видавати 502 через проблеми з таймінгом дереєстрації або збої TLS-рукостискання. «Сервіс не працює» — це одна категорія причин, а не визначення помилки.

Ця ментальна модель дає вам реальний чеклист ще до того, як ви торкнетеся будь-якого конфігураційного файлу. Запитайте, в якій категорії ви, мабуть, перебуваєте, а потім шукайте докази. Саме це робить послідовність усунення несправностей логічною, а не ритуальною.

Розумна послідовність усунення помилок 502

Найшвидший спосіб усунути 502 — визначити, який рівень її повернув, а потім перевірити наступний вузол за цим рівнем, перш ніж щось змінювати. Мета — довести, де знаходиться невдала передача.

💡 Порада: Перш ніж перезапускати або редагувати щось, визначте, хто повернув 502. Чіткий крок атрибуції часто економить більше часу, ніж перші п’ять «виправлень», які люди намагаються застосувати під тиском.

Фаза 1: Визначте рівень

Почніть з публічного боку та запитайте, що насправді повертає інтернет-facing рівень:

curl -I https://example.com

Це показує HTTP-статус і заголовки з публічного URL. Якщо заголовки явно належать CDN, load balancer або reverse proxy, у вас є перша підказка. Якщо сторінка помилки брендована Cloudflare, Cloudflare міг сам згенерувати 502; якщо вона небрендована, edge може просто передавати збій з боку origin. Заголовки, такі як cf-error-type або cf-error-origin, можуть з’являтися на сторінках помилок, згенерованих Cloudflare, що корисно саме тому, що вони не з’являються на кожному 502.

📝 Примітка: Якщо помилку бачить лише один відвідувач, тоді як інші можуть отримати доступ до сайту, локальні налаштування VPN, proxy, брандмауера або DNS все одно можуть бути частиною проблеми. 502 зазвичай є серверною, але ізольований клієнтський шлях може ускладнити те, що ви спостерігаєте.

Фаза 2: Перевірте шлях upstream

Щойно ви знаєте, який рівень повернув 502, перевірте наступний вузол за ним. Якщо задіяний reverse proxy, переконайтеся, що і proxy, і backend-сервіс працюють, і що очікуваний слухач існує:

systemctl status nginx
systemctl status <app-service>
ss -tlnp

Замініть <app-service> на назву вашого backend-сервісу. systemctl status показує, чи живий процес proxy або застосунку, чи він завершився з помилкою, чи перезапускається. ss -tlnp показує, чи щось насправді прослуховує порт, який ви очікуєте.

Потім перевірте, чи backend відповідає безпосередньо без proxy посередині:

curl -i http://127.0.0.1:3000

Якщо прямий запит працює, але публічний URL все одно повертає 502, backend може бути справним, а реальною проблемою може бути передача. Це вказує на налаштування цілі proxy, невідповідності протоколів, імена хостів upstream, очікування TLS або правила брандмауера, а не лише на код застосунку.

Фаза 3: Використовуйте команди як докази, а не як ритуал

Після прямих перевірок перейдіть до доказів, які пояснюють, чому передача зазнає невдачі:

journalctl -u nginx -u <app-service> --since "15 min ago"
dig +short example.com
nginx -t

Ці три перевірки відповідають на різні питання. journalctl виявляє нещодавні збої, скидання, підказки щодо тайм-ауту та збої, пов’язані з деплоєм. dig +short показує, чи розв’язується ім’я хоста, від якого ви залежите, так, як очікує сервер. nginx -t перевіряє синтаксис reverse proxy перед перезавантаженням, що важливо, оскільки неправильне визначення upstream може генерувати 502, навіть коли backend справний.

Практичні сигнали зазвичай виглядають так:

Це основний шаблон для запам’ятовування: визначте рівень, перевірте наступний вузол, а потім використовуйте журнали та прямі тести для пояснення невідповідності. Спочатку докази. Потім налаштування.

Як шлях усунення несправностей змінюється залежно від моделі хостингу

Наступний крок після 502 залежить від того, наскільки ви контролюєте стек. Логіка усунення несправностей залишається тією самою, але обсяг того, що ви можете перевірити самостійно, суттєво відрізняється між shared-хостингом, VPS, виділеними серверами та налаштуваннями з edge-proxy.

📝 Примітка: На shared-хостингу звернення до підтримки — це не відступ. Це часто правильний технічний крок, оскільки рівні, що мають найбільше значення для 502, можуть бути поза вашою видимістю.

На shared-хостингу найкорисніше, що ви можете зробити, — це зібрати докази: час, уражений URL, чи є помилка постійною або переривчастою, і чи вона почалася після деплою або зміни конфігурації. Це дає підтримці щось конкретне для роботи. Якщо ви не контролюєте reverse proxy, сервіс застосунку або журнали сервера, детальна діагностика рівень за рівнем швидко закінчується.

На VPS повний робочий процес стає реалістичним, оскільки ви можете безпосередньо перевіряти сервіси, слухачів, журнали та конфігурацію proxy. Саме тут належить усунення несправностей reverse proxy. На інфраструктурі AlexHost VPS перевірка systemctl, journalctl, ss, цілей upstream та конфігурації Nginx є частиною нормального управління, а не чимось, що завжди приховане за підтримкою.

Виділений сервер дає вам таку саму видимість, але з більшою відповідальністю. Ви контролюєте більше повного стеку і, можливо, більше навколишніх мережевих припущень. Якщо ви додаєте CDN або інший edge-сервіс попереду, перше питання щодо відповідальності залишається тим самим: чи edge згенерував 502, чи переслав збій з боку origin? Більший контроль не робить усунення несправностей простішим за замовчуванням. Він дає вам більше місць для перевірки.

Мисліть рівнями, а не панікою

Помилка 502 Bad Gateway перестає здаватися загадковою, щойно ви сприймаєте її такою, якою вона зазвичай є: невдалою передачею між серверами, а не випадковою подією в браузері. Браузер — це лише місце, де ви її помічаєте. Справжня історія знаходиться на рівні, який передає запит наступному і не отримує нічого придатного у відповідь.

Тому тримайте послідовність простою: визначте рівень, перевірте наступний вузол, перевірте за допомогою прямих тестів і журналів, і змінюйте налаштування лише тоді, коли докази вказують на щось конкретне. Якщо повторювані інциденти постійно штовхають вас до глибшої видимості журналів, proxy та сервісів, саме тут середовища з вищим рівнем контролю — включаючи AlexHost VPS або виділені сервери — стають корисними з операційних причин, а не маркетингових. Метод перемагає запам’ятовування.