Ошибка 504 Gateway Timeout: полное руководство

504 Gateway Timeout — одна из самых частых ошибок в web-инфраструктуре. Она означает, что сервер-шлюз (reverse proxy, CDN, API gateway, ingress) не дождался ответа от upstream-сервера за отведенное время.

Если коротко: запрос дошел до фронтового узла, но где-то дальше в цепочке ответ пришел слишком поздно или не пришел вообще. В этом руководстве разберем, что значит ошибка 504, как быстро найти узкое место и как настроить систему так, чтобы таймауты не били по пользователям и выручке.

Что означает 504 Gateway Timeout

Типичный путь запроса:

Клиент -> CDN/WAF
CDN/WAF -> Nginx/Ingress/API Gateway
Gateway -> приложение
Приложение -> БД/кэш/внешние API

504 gateway timeout возникает на промежуточном узле, который ждет ответ от следующего слоя, но превышает configured timeout.

Это не обязательно «падение» сервиса. Часто сервис жив, но отвечает слишком медленно.

Чем 504 отличается от 502 и 503

502 Bad Gateway — upstream вернул некорректный ответ
503 Service Unavailable — сервис временно недоступен
504 Gateway Timeout — сервис не ответил в срок

Различие важно для диагностики. При 504 фокус обычно на latency и зависимостях.

Почему возникает ошибка 504

1) Медленные SQL-запросы и блокировки

Один тяжелый запрос к БД может занять секунды или десятки секунд. Если таймаут gateway меньше этого времени, клиент увидит 504.

Типичные причины:

отсутствуют индексы
N+1-запросы
lock contention
конкуренция за дисковый I/O

2) Внешние API отвечают слишком долго

Приложение может зависеть от платежных, CRM, email- или anti-fraud-сервисов. Если внешний API «подвис», ваш endpoint легко уходит в timeout.

3) Перегрузка приложения

При высоком трафике растет очередь обработки, p95/p99 latency увеличиваются, и gateway начинает обрывать долгие запросы.

4) Неправильные таймауты между слоями

Если таймауты несогласованы, возникают ложные 504:

CDN ждет 30s
Nginx ждет 60s
приложение может отвечать до 70s

Итог: верхний слой закрывает соединение раньше.

5) Сетевые задержки и проблемы маршрутизации

Потери пакетов, перегруженный канал, нестабильный DNS и межзональные задержки тоже приводят к timeout.

504 как исправить: пошаговая диагностика

Шаг 1. Определите, кто возвращает 504

Проверьте:

response headers
страницу ошибки (CDN, Nginx, gateway)
access/error логи edge-слоя

Это сразу сужает область поиска.

Шаг 2. Проверьте метрики latency

Смотрите не только среднее время, но и хвосты распределения:

p95/p99 response time
queue wait time
upstream response time

Если p99 резко растет перед 504, причина почти всегда в перегрузке или медленных зависимостях.

Шаг 3. Проверьте логи прокси и приложения

Для Nginx:

sudo tail -n 300 /var/log/nginx/error.log
sudo tail -n 300 /var/log/nginx/access.log

Для приложения:

journalctl -u app.service -n 300 --no-pager

Ищите:

upstream timed out
длительные транзакции
timeout к БД/Redis/API

Шаг 4. Проверьте базу и внешние зависимости

Если endpoints зависят от БД:

посмотрите slow query log
проверьте блокировки
сравните load и I/O latency

Если есть внешние API:

соберите статистику по времени ответа
включите retry с ограничением
добавьте fallback/деградацию

Шаг 5. Проверьте цепочку таймаутов

Таймауты должны быть согласованы по всей цепочке:

client timeout
CDN timeout
gateway timeout
application timeout
database timeout

Ошибочно увеличивать только один слой. Нужно проектировать end-to-end budget времени.

Практические решения для 504

1) Оптимизируйте медленные операции

ускорьте SQL (индексы, планы, батчи)
уберите тяжелые синхронные операции из request-path
кэшируйте часто запрашиваемые данные
предварительно вычисляйте дорогие результаты

2) Разделите «быстрые» и «тяжелые» запросы

Тяжелые задачи (отчеты, экспорт, пересчет) лучше переводить в асинхронную модель:

клиент получает 202 Accepted
фоновая задача обрабатывается в очереди
статус возвращается отдельным endpoint

3) Настройте таймауты осмысленно

Принцип:

короткие таймауты для внешних API
чуть выше для приложения
еще выше на gateway
повторные попытки ограничены и с backoff

4) Добавьте защиту от перегрузки

лимиты concurrency
ограниченные очереди
load shedding на некритичных маршрутах
rate limiting для шумного трафика

5) Улучшите deployment-практики

canary перед full rollout
автоматический rollback при росте p99/5xx
прогрев соединений и кэша

Как предотвратить 504 на системном уровне

Наблюдаемость

Минимальный набор:

p50/p95/p99 latency по endpoint
upstream response time
errors by dependency
queue depth и queue time

SLO и алерты

Задайте пороги:

доля 504 > X% за 5 минут
p99 > Y ms
timeout внешнего API > Z%

Алерты должны срабатывать до массового пользовательского сбоя.

Runbooks

Для дежурной команды должен быть четкий сценарий:

где смотреть в первую минуту
как локализовать слой
какие безопасные действия делать первыми

CTA: проактивный мониторинг, чтобы ловить 504 до жалоб клиентов

504 как исправить — правильный вопрос во время инцидента. Но еще важнее получить сигнал до эскалации.

В Statuser можно:

мониторить HTTP-эндпоинты и API
фиксировать рост latency и таймаутов
получать мгновенные уведомления в мессенджеры и email
видеть стабильность сервиса в динамике

Подключите мониторинг заранее, чтобы узнавать о 504 gateway timeout раньше пользователей: https://statuser.cloud.

Итог

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

Если просто увеличить timeout, проблема обычно возвращается: чаще всего корень в медленном бэкенде, зависимостях или сети. В смежных кейсах полезно сверяться с разбором 502, 503, Cloudflare 52x и общим справочником HTTP-кодов, особенно если нужно оценить влияние сбоев на SEO и пользовательский путь.

Если добавить к этому постоянный HTTP-мониторинг и внятные алерты, 504 перестает быть внезапной поломкой и становится контролируемым техническим риском.