Nginx error_page: свои страницы ошибок

error_page перенаправляет обработку ошибки на внутренний URI или named location. Так можно показать брендированную страницу 404, отдать JSON для API или перехватить ошибки upstream. По умолчанию Nginx сохраняет исходный статус ответа, а суффикс =200 или =301 позволяет его изменить.

Показать свои 404 и 50x

server {
    listen 80;

    error_page 404 /404.html;
    error_page 500 502 503 504 /50x.html;

    location = /404.html {
        internal;
        return 200 "Страница не найдена";
    }

    location = /50x.html {
        internal;
        return 200 "Сервис временно недоступен";
    }

    location /api/ {
        proxy_pass http://backend;
        proxy_intercept_errors on;
    }
}

internal запрещает открывать /404.html и /50x.html напрямую: они доступны только как результат внутреннего перенаправления. Статус ответа остаётся 404 или 500, даже если location возвращает 200; клиент и поисковики видят правильный код. Для SPA fallback используют error_page 404 =200 /index.html;, но это скрывает настоящие 404 у несуществующих API-маршрутов.

proxy_intercept_errors on нужен, чтобы Nginx обрабатывал error_page для ответов upstream. Без него 500 от приложения уйдёт клиенту как есть. Не включайте перехват для API, если клиент ожидает исходный JSON ошибки; лучше вернуть JSON из приложения.

Цепочка error_page может зациклиться, если целевая страница тоже отдаёт ошибку. Директива recursive_error_pages on разрешает ещё один переход, но увеличивает риск цикла; используйте её только с проверенным fallback. Для повторного запроса к другому бэкенду удобен named location: error_page 502 = @reserve;.

Проверяйте nginx -t после изменений и помните, что внутренний редирект на URI меняет метод на GET для всех методов, кроме GET и HEAD. Если для POST/PUT нужно сохранить метод, используйте named location: error_page 404 = @fallback;.

Документация: ngx_http_core_module: error_page, proxy_intercept_errors.