Введение

Эта инструкция посвящена одной узкой, но очень коварной группе проблем: запрос не проходит или проходит частично из-за того, что его заголовки или куки стали слишком большими. Внешне это выглядит как ошибка 431 Request Header Fields Too Large, как специфичный для nginx код 494 Request Header Too Large, как невнятный 400 Request Header Or Cookie Too Large, а в худшем случае вообще никак не выглядит: какой-то промежуточный узел молча отбрасывает часть заголовков, и приложение получает пользователя без сессии, без токена авторизации или без нужных куки.

Важно сразу отстроиться от соседней темы. В отдельной статье мы разбирали коды 407, 502 и 504, которые выдает сам прокси-слой при установке туннеля: не прошла авторизация на прокси, не поднялся апстрим, истек таймаут. Там проблема в соединении и в самом прокси. Здесь же соединение устанавливается нормально, туннель есть, но данные, которые вы пытаетесь через него отправить, не помещаются в буферы одного из узлов цепочки. Причина всегда в объеме и составе заголовков, и лечится она совершенно другими инструментами.

Что вы получите в итоге

  • Умение за несколько минут точно измерить размер заголовков и куки конкретного запроса.
  • Понимание, какой именно узел цепочки (браузер или клиент, прокси, балансировщик, веб-сервер, приложение) отказывает или обрезает данные.
  • Готовый эхо-эндпоинт для выявления тихого обрезания без единого кода ошибки.
  • Рабочие конфигурации лимитов для nginx, Apache, Node.js, HAProxy, Tomcat и Gunicorn с пояснением каждого параметра.
  • Стратегию уменьшения куки, чтобы проблема не вернулась через месяц.
  • Мониторинг, который будет сигналить о приближении к лимиту заранее.

Для кого этот гайд

Для веб-разработчиков, системных администраторов, специалистов по парсингу и автоматизации, а также для тех, кто работает с большим числом аккаунтов через прокси и регулярно сталкивается с непонятными отказами. Уровень сложности средний: вам не нужно быть экспертом по протоколу HTTP, но базовые навыки работы с терминалом и понимание, что такое конфигурационный файл, понадобятся.

Что нужно знать заранее

  • Как открыть терминал и выполнить команду.
  • Как открыть панель разработчика в браузере (клавиша F12).
  • Где лежат конфиги вашего веб-сервера, если вы его администрируете.
  • Общее представление о том, что запрос идет от клиента через промежуточные узлы к серверу.

Сколько времени потребуется

Диагностика по шагам 1-4 занимает от 30 до 60 минут. Исправление на стороне сервера (шаги 5-7) займет еще 1-2 часа с учетом перезапусков и проверок. Если вы только проверяете чужой сервис и не имеете доступа к его настройкам, вам хватит первых четырех шагов и раздела про уменьшение куки.

Предварительная подготовка

Ничего экзотического не потребуется, но подготовьте инструменты заранее, чтобы не отвлекаться в процессе.

Необходимые инструменты

  • curl версии 7.70 или новее. Он есть в macOS, во всех дистрибутивах Linux и в Windows 10 и 11 из коробки. Проверьте командой curl --version.
  • Браузер с панелью разработчика: Chrome, Edge, Firefox или Яндекс Браузер. Понадобится вкладка Network (Сеть) и вкладка Application или Storage для просмотра куки.
  • Текстовый редактор с подсветкой: VS Code, Notepad++ или встроенный nano на сервере.
  • Доступ по SSH к серверу, если вы будете менять лимиты. Права на чтение логов и перезапуск сервисов обязательны.
  • Python 3 или Node.js для запуска эхо-эндпоинта. Хватит любой актуальной версии.
  • Опционально: mitmproxy или встроенный анализатор в антидетект-браузере, если вы хотите смотреть трафик между клиентом и прокси.

Системные требования

Любая рабочая машина. Для эхо-сервера достаточно 100 МБ оперативной памяти. Единственное реальное требование: сетевой доступ к проверяемому сервису и, при необходимости, к используемому прокси.

Что скачать и настроить

  1. Убедитесь, что curl работает: выполните curl -sI https://example.com. Вы должны увидеть строки заголовков ответа, начиная с HTTP/2 200 или похожей.
  2. Если работаете через прокси, подготовьте его адрес, порт, логин и пароль. Проверьте базовое соединение командой curl -x http://логин:пароль@host:port -sI https://example.com. Если здесь ошибка 407 или соединение вообще не устанавливается, вернитесь к статье про коды прокси-слоя: наша тема начинается только после успешного туннеля.
  3. На сервере найдите основной конфиг: для nginx это обычно /etc/nginx/nginx.conf и папка /etc/nginx/conf.d/, для Apache /etc/apache2/apache2.conf или /etc/httpd/conf/httpd.conf.
  4. Найдите логи: /var/log/nginx/error.log, /var/log/nginx/access.log, /var/log/apache2/error.log. Убедитесь, что можете читать их командой tail -n 50.

Резервные копии

Перед любой правкой конфигов сделайте копию. Это занимает секунды и спасает часы.

  1. Выполните sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak-2026.
  2. Для папки с сайтами: sudo cp -r /etc/nginx/conf.d /etc/nginx/conf.d.bak-2026.
  3. Для Apache аналогично: sudo cp /etc/apache2/apache2.conf /etc/apache2/apache2.conf.bak-2026.
  4. Запишите текущие значения лимитов в отдельный файл заметок, чтобы понимать, откуда вы стартовали.

Внимание: никогда не правьте боевой конфиг без предварительной проверки синтаксиса. Для nginx это sudo nginx -t, для Apache sudo apachectl configtest. Ошибка в одной строке при перезапуске оставит сервис лежать.

Базовые понятия

Прежде чем ловить проблему, договоримся о терминах. Здесь нет ничего сложного, но путаница в словах часто уводит диагностику не туда.

Что такое заголовки запроса

Любой HTTP-запрос состоит из стартовой строки (метод, путь, версия протокола), блока заголовков и опционального тела. Заголовки это пары вида Имя: значение. Браузер добавляет их автоматически: Host, User-Agent, Accept, Accept-Language, Referer, Authorization и, конечно, Cookie. Приложения добавляют свои: токены, идентификаторы трассировки, признаки эксперимента.

Почему куки самый частый виновник

Заголовок Cookie собирается из всех куки, подходящих под домен и путь запроса. Каждая аналитическая система, каждый виджет чата, каждая рекламная сеть добавляет по несколько штук. Значение одной куки может быть до 4 КБ, а таких куки на домене десятки. При этом браузер отправляет их со всеми запросами, включая картинки и шрифты. В результате заголовок Cookie легко перерастает 8-16 КБ, а именно такие пороги стоят по умолчанию у большинства серверов.

Код 431

431 Request Header Fields Too Large это стандартный код, описанный в спецификации HTTP. Сервер сообщает: заголовки слишком велики, либо один из них, либо все вместе. Код возвращают Node.js, Go, Envoy, некоторые CDN и современные фреймворки. Ответ с 431 корректен по протоколу и хорошо виден в логах, поэтому это самый удобный для диагностики вариант.

Код 494

494 Request Header Too Large это внутренний нестандартный код nginx. Nginx использует его в своем коде, когда заголовок не помещается в буферы, заданные директивой large_client_header_buffers. При этом клиенту по умолчанию отправляется 400 с телом Request Header Or Cookie Too Large. Увидеть именно цифру 494 можно в двух случаях: если администратор явно описал error_page 494, или если вы читаете внутренние переменные и логи nginx. Поэтому если пользователь жалуется на белую страницу с надписью 400 и словами про cookie, знайте: это тот же 494.

Тихое обрезание

Самый неприятный сценарий. Промежуточный узел не отвергает запрос, а обрезает заголовок по размеру своего буфера или отбрасывает часть заголовков целиком. Приложение получает неполные данные. Симптомы разнообразны: пользователя внезапно разлогинивает, теряется корзина, не читается токен, пропадает заголовок с идентификатором региона. Кода ошибки нет, в логах веб-сервера все зеленое. Такое поведение встречается у самописных прокси на фиксированных буферах, у старых корпоративных шлюзов, у некоторых WAF в режиме мягкой обработки, у клиентских библиотек, которые дробят или урезают длинные значения, а также в самом браузере, который молча игнорирует Set-Cookie длиннее 4096 байт.

Где вообще стоят лимиты

Представьте цепочку: браузер или скрипт, затем ваш исходящий прокси (например, мобильный), затем CDN или WAF, затем балансировщик, затем веб-сервер, затем сервер приложения. У каждого звена свой лимит и свое поведение при превышении. Задача диагностики найти самое узкое место. Именно поэтому просто увеличить лимит в nginx часто недостаточно: за ним стоит Node.js со своим порогом в 16 КБ.

Граница с ошибкой 502 upstream sent too big header

Отдельный случай на стыке двух тем. Если nginx пишет в error.log фразу upstream sent too big header while reading response header from upstream и отдает 502, то дело не в туннеле и не в падении апстрима, а в заголовках ответа приложения, которые не влезли в proxy_buffer_size. Формально это 502, но лечится параметрами буферов, о которых мы говорим здесь. Запомните этот маркер: он поможет не искать проблему в прокси-слое.

Шаг 1: Воспроизвести проблему и зафиксировать симптомы

Цель этапа: получить стабильный сценарий, при котором ошибка возникает, и записать точные признаки: код, текст ответа, заголовок Server и время.

  1. Откройте проблемную страницу в браузере. Нажмите F12, перейдите на вкладку Network (Сеть).
  2. Установите флажок Preserve log (Сохранять журнал), чтобы записи не пропадали при переходах.
  3. Перезагрузите страницу клавишей F5. Найдите запрос, окрашенный красным, или запрос со статусом 400, 431 или 494. Кликните по нему.
  4. На вкладке Headers запишите: статус-код, значение заголовка Server в ответе (nginx, cloudflare, AkamaiGHost, gunicorn), значение Via, если есть, и любые заголовки с префиксом X- или CF-.
  5. Перейдите на вкладку Response и скопируйте тело ответа. Фраза Request Header Or Cookie Too Large указывает на nginx. Фраза Request Header Fields Too Large без слова Cookie типична для Node.js. Фраза Bad Request - Request Too Long характерна для IIS.
  6. Прокрутите вниз до блока Request Headers. Прикиньте длину строки Cookie: если она занимает несколько экранов, это уже подсказка.
  7. Откройте окно в режиме инкогнито и повторите запрос. Если в чистом профиле ошибки нет, виноваты накопленные куки конкретного пользователя.

Если проблема воспроизводится в скрипте, а не в браузере, зафиксируйте те же данные из ответа библиотеки: статус, тело, заголовки. В Python requests это response.status_code, response.text и response.headers.

Совет: сделайте экспорт всех запросов в файл HAR правой кнопкой мыши по списку запросов и пунктом Save all as HAR with content. Этот файл можно открыть позже или передать коллеге, и он сохранит точные размеры заголовков.

Проверка: у вас должна быть заметка с четырьмя пунктами: статус-код, текст тела ответа, значение заголовка Server и результат теста в инкогнито. Если результат в инкогнито отличается, вы уже на 70 процентов знаете причину.

Возможные проблемы

  • Ошибка проявляется не всегда. Значит, размер куки плавает около порога: например, после посещения определенного раздела добавляется еще одна кука. Запишите, после каких действий ошибка появляется.
  • Красного запроса нет, но страница работает неправильно. Это признак тихого обрезания. Переходите к шагу 4 сразу после измерения.

Шаг 2: Измерить реальный размер заголовков и куки

Цель этапа: получить точные цифры в байтах: общий размер блока заголовков, размер заголовка Cookie, размер каждой отдельной куки.

Измерение в браузере

  1. В панели разработчика откройте вкладку Console (Консоль).
  2. Введите document.cookie.length и нажмите Enter. Вы увидите число: это длина в символах всех куки, доступных скриптам, без флага HttpOnly. Реальный заголовок будет больше, потому что HttpOnly-куки сюда не входят.
  3. Введите document.cookie.split('; ').map(c => [c.split('=')[0], c.length]).sort((a, b) => b[1] - a[1]). Консоль покажет массив пар имя-длина, отсортированный по убыванию. Самые тяжелые куки окажутся сверху.
  4. Перейдите на вкладку Application (в Firefox Storage), раскройте Cookies, выберите домен. Здесь видны все куки, включая HttpOnly, с колонкой Size. Кликните по заголовку колонки, чтобы отсортировать по размеру.
  5. Сложите размеры или просто посмотрите на строку Cookie в запросе из шага 1: в Chrome при наведении на заголовок отображается его длина.

Измерение через curl

Curl позволяет отправить заголовки любого размера и точно узнать, на каком объеме сервер начинает отказывать. Сгенерируем куку контролируемой длины.

  1. Создайте строку из 8000 символов. В Linux и macOS: BIG=$(head -c 8000 /dev/zero | tr '\0' 'a'). Если оболочка ругается на экранирование, используйте вариант BIG=$(python3 -c "print('a'*8000)").
  2. Отправьте запрос: curl -s -o /dev/null -w '%{http_code}' -H "Cookie: test=$BIG" https://ваш-сайт.ru/. На экране появится только код ответа.
  3. Меняйте размер: 4000, 8000, 12000, 16000, 32000, 64000. Запишите, при каком значении код меняется с 200 на 400 или 431.
  4. Если работаете через прокси, добавьте -x http://логин:пароль@host:port и повторите серию. Разница между порогами с прокси и без него покажет, есть ли лимит на самом прокси.

Пример бинарного поиска порога в одну команду для bash:

for n in 4000 8000 12000 16000 24000 32000 64000; do BIG=$(python3 -c "print('a'*$n)"); echo -n "$n: "; curl -s -o /dev/null -w '%{http_code}' -H "Cookie: t=$BIG" https://ваш-сайт.ru/; echo; done

В Windows PowerShell аналог: $big = 'a' * 16000; curl.exe -s -o NUL -w '%{http_code}' -H "Cookie: t=$big" https://ваш-сайт.ru/.

Интерпретация цифр

  • Порог около 8 КБ: типично для Apache с настройками по умолчанию, Tomcat, Gunicorn, а также для nginx, когда заголовок не влезает в один буфер из четырех по 8 КБ.
  • Порог около 16 КБ: Node.js начиная с 13 версии, HAProxy с базовым tune.bufsize, IIS.
  • Порог около 32 КБ: суммарный лимит некоторых CDN. Отдельный заголовок там часто ограничен 16 КБ.
  • Порог около 60-64 КБ: Envoy и часть облачных балансировщиков.
  • Порог около 1 МБ: стандартный сервер Go.

Совет: измеряйте не только Cookie. Повторите серию с заголовком Authorization: Bearer $BIG и с несколькими заголовками поменьше. Некоторые серверы ограничивают отдельно размер одного поля, отдельно их количество и отдельно общий объем. Nginx, например, по умолчанию не пропустит один заголовок больше 8 КБ даже при небольшом общем размере, потому что каждая строка должна поместиться в отдельный буфер.

Проверка: в заметках должно появиться число, при котором сервер начинает отказывать, и список трех-пяти самых тяжелых куки с их размерами. Если порог не найден до 64 КБ, а ошибка в браузере есть, значит, отказывает не сервер, а что-то между браузером и сервером в вашем конкретном окружении. Переходите к следующему шагу.

Шаг 3: Определить, какой слой отказывает

Цель этапа: точно назвать узел цепочки, который возвращает ошибку или режет данные, чтобы менять настройки именно там.

Чтение подписи ответа

  1. Выполните curl -sv -H "Cookie: t=$BIG" https://ваш-сайт.ru/ 2>&1 | grep -i -E 'server|via|cf-|x-served|x-cache|HTTP/', где BIG заведомо превышает порог.
  2. Прочитайте заголовок Server. Значение nginx с телом Request Header Or Cookie Too Large означает, что отказал nginx. Значение cloudflare означает, что до вашего сервера запрос не дошел. Пустой Server и тело в формате JSON часто указывает на приложение.
  3. Обратите внимание на версию протокола в первой строке. Если при нормальных запросах сервер отвечает по HTTP/2, а ошибка приходит по HTTP/1.1, это признак, что ответ сформирован промежуточным узлом, а не конечным.
  4. Сравните тела ошибок: страница nginx лаконична и содержит его имя внизу; страница Cloudflare содержит Ray ID; Node.js часто возвращает пустое тело со статусом 431.

Обход слоев

  1. Если у вас есть прямой IP-адрес сервера за CDN, повторите запрос с ключом --resolve ваш-сайт.ru:443:1.2.3.4. Это заставит curl подключиться напрямую, сохранив правильный Host и SNI. Если напрямую запрос проходит, а через CDN нет, лимит стоит на CDN.
  2. Если у вас есть доступ на сервер, выполните запрос локально: curl -s -o /dev/null -w '%{http_code}' -H "Cookie: t=$BIG" -H 'Host: ваш-сайт.ru' http://127.0.0.1:80/. Так вы исключаете все внешние узлы.
  3. Затем стучите прямо в приложение, минуя nginx: curl ... http://127.0.0.1:3000/ для Node.js или порт, на котором слушает Gunicorn. Если nginx пропускает, а приложение отвечает 431, лимит стоит в приложении.
  4. Проверьте влияние своего исходящего прокси: одна серия запросов с -x, одна без. Для HTTPS-запросов через прокси используется метод CONNECT, и прокси не видит заголовков внутри шифрованного туннеля, поэтому влиять на их размер не может. Но для обычных HTTP-запросов прокси разбирает заголовки сам, и здесь уже возможен собственный лимит и даже обрезание.

Чтение логов на сервере

  1. Выполните sudo tail -f /var/log/nginx/error.log и повторите проблемный запрос.
  2. Строка client sent too long header line подтверждает, что отдельная строка заголовка превысила буфер nginx. Строка client sent too large request говорит о переполнении суммарного объема.
  3. Для Apache в error.log ищите Request header exceeds LimitRequestFieldSize или Size of a request header field exceeds server limit.
  4. Для Node.js в логах приложения: ошибка HPE_HEADER_OVERFLOW, это внутренний код парсера, который снаружи превращается в 431.
  5. В access.log nginx посмотрите поле с размером запроса. Если вы используете стандартный формат, добавьте в log_format переменную $request_length: она покажет полный размер запроса вместе с заголовками и будет полезна для мониторинга.

Внимание: если в error.log nginx вы видите upstream sent too big header, отказывает не входящий запрос, а ответ вашего приложения, чьи заголовки не влезают в буфер nginx. Такой случай выглядит как 502, но относится к нашей теме. Причина обычно в гигантском Set-Cookie или в десятках заголовков от фреймворка. Решение в шаге 6.

Проверка: вы должны уверенно сказать одно из: отказывает CDN; отказывает nginx; отказывает Apache; отказывает приложение; отказывает прокси на моей стороне. Если картина неоднозначна, значит, лимит превышен сразу на нескольких узлах, и придется править их все по очереди, каждый раз повторяя тест из шага 2.

Шаг 4: Выявить тихое обрезание с помощью эхо-эндпоинта

Цель этапа: убедиться, что заголовки доходят до приложения ровно в том виде, в котором отправлены, и поймать узел, который молча их меняет.

Идея простая. Мы поднимем маленький сервер, который возвращает в ответе все полученные заголовки и их размеры. Отправим заголовок известной длины с контрольной суммой и сравним, что пришло.

Запуск эхо-сервера на Python

  1. Создайте файл echo.py со следующим содержимым:
import hashlib, json
from http.server import BaseHTTPRequestHandler, HTTPServer

class H(BaseHTTPRequestHandler):
def do_GET(self):
out = {}
total = 0
for k, v in self.headers.items():
total += len(k) + len(v) + 4
out[k] = {"len": len(v), "sha": hashlib.sha256(v.encode()).hexdigest()[:12]}
out["_total"] = total
out["_count"] = len(self.headers)
body = json.dumps(out, indent=1).encode()
self.send_response(200)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)

HTTPServer(("0.0.0.0", 8089), H).serve_forever()
  1. Запустите: python3 echo.py. Сервер слушает порт 8089.
  2. Разместите его там, где стоит ваше настоящее приложение, или временно направьте на него один location в nginx: location /__echo { proxy_pass http://127.0.0.1:8089; }. Тогда запрос пройдет через всю реальную цепочку.

Учтите, что стандартный HTTPServer Python не имеет жесткого лимита на длину заголовков, но ограничивает их количество сотней. Для теста этого достаточно.

Отправка контрольного запроса

  1. Сгенерируйте значение из 12000 символов, но не однородное, а с маркерами позиции, чтобы видеть, откуда отрезано: V=$(python3 -c "print(''.join(str(i%10) for i in range(12000)))").
  2. Посчитайте эталонный хэш: python3 -c "import hashlib,sys; print(hashlib.sha256(sys.argv[1].encode()).hexdigest()[:12])" "$V".
  3. Отправьте через всю цепочку: curl -s -H "Cookie: probe=$V" -H "X-Probe-Len: 12000" https://ваш-сайт.ru/__echo.
  4. Сравните в ответе поле len для Cookie с числом 12006 (имя probe плюс знак равенства плюс 12000 символов) и хэш с эталоном.
  5. Повторите с несколькими заголовками: добавьте 30 заголовков X-Test-1 ... X-Test-30 и проверьте поле _count.

Как читать результат

  • Длина совпала, хэш совпал: обрезания на этом пути нет.
  • Длина меньше, заголовок оборван: кто-то отрезал хвост. Посмотрите последний символ пришедшего значения: он подскажет позицию среза, часто это ровная граница 4096 или 8192 байт.
  • Заголовок отсутствует целиком: узел отбросил поле, не поместившееся в буфер. Так ведут себя некоторые WAF и старые шлюзы.
  • _count меньше отправленного: достигнут лимит количества заголовков. Apache и Gunicorn по умолчанию принимают 100 полей, HAProxy 101, и часть реализаций отбрасывает лишние молча.
  • Длина совпала, хэш не совпал: узел изменил содержимое. Такое бывает при нормализации пробелов или перекодировании; проверьте, нет ли в значении символов, которые прокси считает недопустимыми.

Совет: если вы работаете через мобильный или иной внешний прокси, поднимите эхо-сервер на публично доступном хосте и прогоните запросы через прокси в обычном HTTP без TLS. Именно в этом режиме прокси разбирает заголовки сам и может показать свои лимиты. В режиме HTTPS через CONNECT содержимое для прокси непрозрачно, и обрезание на этом слое физически невозможно.

Проверка: у вас есть таблица: узел, отправлено байт, получено байт, совпадение хэша. Если все строки совпадают, тихого обрезания нет, и ваши симптомы объясняются явными отказами из шагов 1-3. Если есть расхождение, вы знаете, где именно.

Отдельная проверка браузера на Set-Cookie

Браузер тоже режет молча, но не запрос, а ответ. Если сервер отправляет Set-Cookie длиннее примерно 4096 байт, Chrome и Firefox его просто игнорируют, без единого предупреждения. Проверьте: на вкладке Network найдите ответ с Set-Cookie, посмотрите длину строки, затем откройте вкладку Application и убедитесь, что кука сохранилась. Если ее нет, разбивайте значение на части или переносите данные на сервер.

Шаг 5: Уменьшить объем куки и заголовков

Цель этапа: устранить корень проблемы, чтобы запросы помещались в стандартные лимиты и не зависели от милости промежуточных узлов.

Поднять лимиты соблазнительно, но это лечение симптома. Каждый лишний килобайт куки уходит с каждым запросом каждого пользователя, включая запросы за картинками. Начните с сокращения.

Аудит куки

  1. Возьмите список из шага 2, отсортированный по размеру.
  2. Для каждой куки ответьте на три вопроса: кто ее ставит, нужна ли она серверу, нужна ли она на каждом пути сайта.
  3. Куки аналитических систем и рекламных пикселей серверу почти никогда не нужны. Их не нужно удалять, но их нужно не отправлять на API-домен.
  4. Куки с сериализованным состоянием (корзина в JSON, настройки интерфейса, история просмотров) кандидаты на перенос в localStorage или в серверное хранилище с коротким идентификатором.

Приемы сокращения

  1. Вынесите API на отдельный поддомен. Куки, установленные на www.сайт.ru без явного Domain, не отправляются на api.сайт.ru. Тяжелые маркетинговые куки останутся на витрине, а API получит только сессию.
  2. Задавайте атрибут Path. Кука с Path=/admin не уйдет в запросы к /static. Проверьте, что ваши фреймворки не ставят все куки на корень без нужды.
  3. Храните в куке идентификатор, а не данные. Вместо JSON на 3 КБ положите 32-символьный ключ и держите данные в Redis или базе. Заодно решится проблема подделки содержимого.
  4. Сокращайте JWT. Токен в куке или в Authorization раздувается из-за лишних полей в payload: списка ролей, адреса, аватара. Оставьте идентификатор и срок жизни, остальное запрашивайте отдельным вызовом. Типичный JWT должен укладываться в 500-800 байт.
  5. Удаляйте устаревшие куки явно. Если вы переименовали куку, старая останется у пользователей до истечения срока. Отправьте Set-Cookie со старым именем и Max-Age=0.
  6. Используйте отдельный домен без куки для статики. Классический прием: static.сайт.ru или CDN-домен, на который куки не ставятся вообще.
  7. Проверьте дублирование. Часто одна и та же кука существует в двух вариантах: для сайт.ru и для .сайт.ru с точкой. Браузер отправит обе.

Для скриптов и автоматизации

Если вы управляете множеством аккаунтов через прокси и антидетект-браузеры, следите за профилями. Профиль, живущий полгода, накапливает куки десятков сторонних доменов, и запросы к целевому сайту начинают отказывать именно из-за раздутого заголовка. Настройте периодическую очистку куки сторонних доменов, не трогая куки авторизации целевого сайта. В библиотеках вроде requests или httpx храните куки в отдельном CookieJar на аккаунт и раз в сутки удаляйте записи с истекшим сроком.

Совет: добавьте на клиенте простую проверку перед запросом: если document.cookie.length превышает 6000 символов, отправьте метрику в вашу систему аналитики. Так вы узнаете о проблеме от первых пользователей, а не от массовых жалоб.

Проверка: повторите измерение из шага 2 на чистом профиле, пройдите типичный сценарий пользователя (вход, каталог, корзина, оформление) и убедитесь, что суммарный размер заголовков не превышает 4 КБ на API и 8 КБ на витрине. Это комфортный запас относительно любых стандартных лимитов.

Шаг 6: Настроить лимиты на веб-сервере, балансировщике и в приложении

Цель этапа: установить согласованные лимиты на всех узлах, которыми вы управляете, так чтобы ни один из них не был неожиданно уже соседей.

Золотое правило: лимит внешнего узла должен быть не больше лимита внутреннего. Иначе nginx пропустит 32 КБ, а Node.js за ним отвергнет с 431, и вы получите ошибку из глубины стека, которую сложнее диагностировать. Разумный ориентир для 2026 года: 16 КБ на весь блок заголовков и 8-16 КБ на отдельное поле. Этого хватает почти всем, при этом остается защита от злоупотреблений.

nginx

  1. Откройте /etc/nginx/nginx.conf. Найдите блок http { ... }.
  2. Добавьте или измените три директивы:
http {
client_header_buffer_size 4k;
large_client_header_buffers 4 16k;
proxy_buffer_size 16k;
proxy_buffers 8 16k;
}
  1. client_header_buffer_size это первый маленький буфер для типичных запросов. Значение 1k по умолчанию заставляет nginx переключаться на большие буферы почти всегда, что не страшно, но 4k снижает лишние аллокации.
  2. large_client_header_buffers 4 16k означает: до четырех буферов по 16 КБ. Каждая строка заголовка должна целиком поместиться в один буфер, а весь блок в сумму буферов. Значит, отдельная кука или Authorization не могут превышать 16 КБ, а все заголовки вместе 64 КБ.
  3. proxy_buffer_size отвечает за первую порцию ответа апстрима, включая его заголовки. Именно его увеличение убирает 502 с фразой upstream sent too big header. Значение proxy_buffers должно быть не меньше, чем proxy_buffer_size.
  4. Если хотите, чтобы клиент видел осмысленный ответ вместо стандартной страницы 400, добавьте внутри server: error_page 494 =431 /431.html; и разместите файл 431.html с понятным текстом и советом очистить куки. Так вы превращаете нестандартный 494 в стандартный 431.
  5. Проверьте синтаксис: sudo nginx -t. Должно появиться syntax is ok и test is successful.
  6. Примените без разрыва соединений: sudo nginx -s reload.

Помните, что large_client_header_buffers можно задать и в контексте server, но для HTTP/2 действует значение из контекста http, поэтому правьте именно там. Для HTTP/2 дополнительно существует директива http2_max_header_size в старых версиях; в актуальных сборках она удалена, и достаточно large_client_header_buffers.

Apache

  1. Откройте главный конфиг и добавьте на уровне сервера или VirtualHost:
LimitRequestFieldSize 16384
LimitRequestFields 150
LimitRequestLine 16384
  1. LimitRequestFieldSize ограничивает одно поле, по умолчанию 8190 байт. LimitRequestFields ограничивает количество полей, по умолчанию 100. LimitRequestLine ограничивает стартовую строку, что важно при длинных URL с параметрами.
  2. Если Apache работает как обратный прокси через mod_proxy_http, добавьте ProxyIOBufferSize 32768 для ответов с большими заголовками.
  3. Проверьте: sudo apachectl configtest, затем sudo systemctl reload apache2.

Node.js

  1. Лимит задается при запуске процесса флагом --max-http-header-size. Значение в байтах: node --max-http-header-size=32768 server.js.
  2. Если вы используете PM2 или systemd, укажите флаг в поле node_args или в переменной окружения NODE_OPTIONS=--max-http-header-size=32768.
  3. Альтернатива в коде: http.createServer({ maxHeaderSize: 32768 }, app). Этот параметр поддерживается в актуальных версиях Node и позволяет задать лимит без перезапуска с новыми флагами.
  4. Проверьте после перезапуска серией curl прямо на порт Node: порог должен сдвинуться.

Tomcat и Spring Boot

  1. В server.xml у элемента Connector добавьте атрибут maxHttpHeaderSize="16384". По умолчанию там 8192.
  2. В Spring Boot достаточно строки в application.properties: server.max-http-request-header-size=16KB. Старое имя свойства server.max-http-header-size тоже работает в ряде версий, но помечено устаревшим.
  3. Перезапустите приложение и проверьте порог.

Gunicorn и Uvicorn

  1. Для Gunicorn добавьте в конфиг или командную строку: --limit-request-field_size 16380 --limit-request-fields 150 --limit-request-line 8190. Обратите внимание на написание field_size с подчеркиванием: это исторический артефакт, и с дефисом параметр не сработает.
  2. Значение 0 у limit-request-field_size снимает ограничение полностью, но не делайте так на публичных серверах.
  3. Uvicorn ограничивает размер заголовков через парсер h11 и по умолчанию допускает довольно большие значения; чаще узкое место находится перед ним, в nginx.

HAProxy

  1. В секции global: tune.bufsize 32768 и tune.http.maxhdr 150.
  2. Запрос целиком вместе со всеми заголовками должен поместиться в один буфер размером tune.bufsize минус резерв tune.maxrewrite. При 16384 по умолчанию реальный доступный объем около 15 КБ.
  3. Проверьте haproxy -c -f /etc/haproxy/haproxy.cfg и перезапустите. Учтите, что увеличение bufsize повышает потребление памяти на каждое соединение.

IIS

  1. Лимиты живут в реестре в ветке HTTP.sys: параметры MaxFieldLength и MaxRequestBytes в ключе HKLM SYSTEM CurrentControlSet Services HTTP Parameters. Значения по умолчанию 16384 байт для обоих, максимум 65534.
  2. После изменения требуется перезапуск службы HTTP или сервера.
  3. Дополнительно проверьте maxAllowedContentLength и maxQueryString в requestFiltering, если проблема касается длинных URL.

CDN и WAF

У большинства облачных CDN лимиты фиксированы на базовых тарифах и меняются только на корпоративных. Если порог из шага 3 упирается в CDN, единственный универсальный путь это уменьшение куки из шага 5. Дополнительно проверьте, не настроен ли на WAF режим, при котором крупные заголовки не блокируются, а вырезаются: такой режим создает то самое тихое обрезание, и его лучше переключить в явный отказ с кодом.

Внимание: не ставьте лимиты в мегабайты ради спокойствия. Каждый килобайт буфера умножается на число одновременных соединений, а атакующий может целенаправленно слать гигантские заголовки, чтобы исчерпать память. Держите разумный запас в два-три раза от реального максимума и не более.

Проверка: повторите серию curl из шага 2 для каждого узла отдельно (напрямую в приложение, через nginx, снаружи через CDN). Пороги должны либо совпадать, либо убывать от внутреннего к внешнему. Убедитесь, что при превышении каждый узел отдает понятный код, а не рвет соединение.

Шаг 7: Сделать отказы явными и настроить мониторинг

Цель этапа: исключить тихое обрезание в будущем и узнавать о росте заголовков до того, как они упрутся в лимит.

Явные ответы вместо молчания

  1. Убедитесь, что каждый ваш узел при превышении лимита возвращает 431 или хотя бы 400 с текстом. В nginx это уже сделано в шаге 6 через error_page 494.
  2. Если у вас самописный прокси или шлюз на фиксированном буфере, добавьте проверку: если заголовок не поместился, отвечайте 431 и закрывайте соединение. Никогда не передавайте дальше усеченное значение.
  3. В приложении добавьте валидацию критичных заголовков. Например, если JWT не парсится или сессионная кука короче ожидаемой длины, логируйте это отдельным событием с пометкой possible truncation. Это дешевый детектор проблем на любом внешнем узле.

Логирование размеров

  1. В nginx расширьте формат лога. В блоке http:
log_format withsize '$remote_addr - $status "$request" req_len=$request_length cookie_len=$cookie_len';
map $http_cookie $cookie_len { default 0; ~^(?<c>.*)$ $c; }
  1. Простой и надежный вариант без map: логируйте только $request_length. Этой переменной достаточно, чтобы видеть рост.
  2. Раз в день выполняйте awk по access.log и находите максимум и 99-й процентиль req_len. Если 99-й процентиль превысил половину лимита, пора чистить куки.
  3. Для Apache используйте в LogFormat переменную %I из mod_logio: она показывает входящие байты вместе с заголовками.

Алерты

  1. Заведите метрику количества ответов 431 и 400 с телом про куки. В Prometheus с nginx-exporter это статусы из access.log; в облачных панелях мониторинга обычно есть разбивка по кодам.
  2. Настройте порог: более 10 таких ответов за 5 минут это сигнал. Массовая ошибка 431 почти всегда означает, что кто-то выкатил новую тяжелую куку.
  3. Добавьте синтетическую проверку: раз в час скрипт отправляет запрос с заголовком на 90 процентов от лимита и проверяет, что он проходит, а с заголовком на 110 процентов проверяет, что возвращается именно 431. Так вы поймаете и случайное ужесточение лимита, и случайное его снятие.

Совет: храните эхо-эндпоинт из шага 4 постоянно, закрыв его по IP или простой авторизацией. Он пригодится при каждом изменении инфраструктуры: добавили WAF, сменили балансировщик, подключили новый прокси-пул, и за минуту можно убедиться, что заголовки доходят целиком.

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

Проверка результата

Пройдитесь по чек-листу. Каждый пункт должен выполняться, иначе вернитесь к соответствующему шагу.

Чек-лист

  • Проблемная страница из шага 1 открывается без ошибок в основном профиле браузера.
  • Суммарный размер заголовков типичного запроса не превышает 8 КБ, а на API-домене 4 КБ.
  • Ни одна кука не превышает 2 КБ, самые тяжелые сторонние куки не отправляются на API.
  • Порог отказа на каждом узле известен и записан; лимиты убывают или совпадают от приложения к внешнему краю.
  • При превышении лимита клиент получает код 431 или 400 с текстом, а не обрыв соединения и не молчаливо урезанный запрос.
  • Эхо-эндпоинт показывает совпадение длины и хэша при отправке через всю цепочку, в том числе через ваши прокси.
  • В access.log присутствует размер запроса, настроен алерт на рост 431.
  • Резервные копии конфигов лежат рядом, и вы знаете команду отката.

Как протестировать целиком

  1. Очистите куки для тестового домена и пройдите пользовательский сценарий от входа до ключевого действия. Ошибок быть не должно.
  2. Запустите цикл curl из шага 2 снаружи. Запишите порог; он должен соответствовать вашим новым настройкам.
  3. Отправьте контрольный запрос на эхо-эндпоинт через каждый используемый путь: напрямую, через CDN, через прокси-пул.
  4. Намеренно отправьте заголовок вдвое больше лимита и убедитесь в получении 431 с понятным телом.
  5. Проверьте, что ответы приложения с большими Set-Cookie не вызывают 502 у nginx.

Показатели успеха

Доля ответов 431 и 400 с текстом про заголовки стремится к нулю в обычном трафике. 99-й процентиль размера запроса меньше половины самого узкого лимита. Разлогинивания без причины и потерянные сессии больше не появляются в обращениях пользователей.

Типичные ошибки и решения

Увеличили лимит в nginx, а 431 остался

Причина: за nginx стоит Node.js или Tomcat со своим лимитом 8-16 КБ, и теперь отказывает он. Решение: проверьте порог прямо на порту приложения из шага 3 и поднимите его флагом --max-http-header-size или maxHttpHeaderSize. Затем убедитесь, что лимит nginx не больше лимита приложения.

Поставили large_client_header_buffers в блок server, но ничего не изменилось

Причина: для HTTP/2 nginx использует значение из контекста http, а также директива не наследуется так, как ожидается, если задана в нескольких server для одного адреса. Решение: перенесите директиву в блок http и перезагрузите конфиг.

Ошибка появляется только у части пользователей

Причина: размер куки зависит от истории конкретного пользователя: посещенных разделов, включенных экспериментов, старых куки с прошлых версий сайта. Решение: соберите статистику размеров через $request_length, найдите, какие куки растут, и явно удаляйте устаревшие через Set-Cookie с Max-Age=0.

После очистки куки все работает, но через неделю ломается снова

Причина: источник роста не устранен: например, скрипт аналитики каждый визит дописывает данные в одну куку. Решение: найдите куку, которая растет, через сортировку по размеру в разные дни, и перенесите ее содержимое в localStorage или ограничьте на стороне поставщика скрипта.

Nginx отдает 502, хотя приложение живо

Причина: в error.log фраза upstream sent too big header: заголовки ответа приложения не влезли в proxy_buffer_size. Обычно виноват огромный Set-Cookie или множество отладочных заголовков. Решение: увеличьте proxy_buffer_size до 16k и proxy_buffers до 8 16k, а в приложении сократите заголовки ответа.

Через прокси запрос по HTTP теряет часть заголовков, а по HTTPS проходит

Причина: для HTTP прокси сам разбирает заголовки и упирается в свой буфер, а для HTTPS через CONNECT содержимое непрозрачно и проходит нетронутым. Решение: перейдите на HTTPS для целевого ресурса или сократите заголовки. Если прокси ваш собственный, поднимите его лимит и настройте явный отказ вместо обрезания.

Браузер не сохраняет куку после ответа сервера

Причина: строка Set-Cookie длиннее 4096 байт или общее число куки на домен превысило лимит браузера (около 180 в Chrome), и он молча отбросил новую или вытеснил старую. Решение: храните в куке только идентификатор, а данные держите на сервере; не создавайте десятки мелких куки, объединяйте их.

Gunicorn игнорирует параметр лимита

Причина: параметр написан с дефисом как limit-request-field-size, а правильное имя содержит подчеркивание: limit-request-field_size. Решение: исправьте написание и перезапустите воркеры.

Дополнительные возможности

Разные лимиты для разных путей

Не обязательно поднимать лимит для всего сайта. Если тяжелые заголовки нужны только на одном пути, например при загрузке файлов с длинными метаданными, в nginx можно вынести этот путь в отдельный server на отдельном имени или порту с увеличенными large_client_header_buffers, а основной сайт оставить строгим. Так вы сохраняете защиту от злоупотреблений там, где она важнее.

Сжатие заголовков в HTTP/2 и HTTP/3

Протоколы HTTP/2 и HTTP/3 сжимают заголовки алгоритмами HPACK и QPACK. По сети повторяющиеся куки уходят компактно, но на сервере они распаковываются в полный размер, и лимиты применяются именно к распакованным данным. Поэтому включение HTTP/2 экономит трафик, но не спасает от 431. Параметр SETTINGS_MAX_HEADER_LIST_SIZE, который сервер объявляет клиенту, задает верхнюю границу распакованного списка; в nginx он вычисляется из large_client_header_buffers автоматически.

Чанкованные куки

Некоторые библиотеки авторизации умеют разбивать длинное значение на несколько куки с суффиксами .0, .1, .2 и собирать обратно на сервере. Это решает проблему лимита браузера на одну куку в 4 КБ, но не уменьшает общий размер заголовка Cookie. Используйте прием только как временную меру при переходе на серверное хранение сессий.

Сессии на сервере вместо куки-контейнеров

Самое надежное архитектурное решение: в куке остается только случайный идентификатор длиной 32-64 символа, а все состояние лежит в Redis с TTL. Заголовок Cookie при этом редко превышает 200 байт, и вся тема лимитов перестает быть актуальной. Переезд занимает от одного дня для небольшого приложения до нескольких недель для крупного, но окупается снижением трафика и упрощением безопасности.

Автоматическая проверка в CI

Добавьте в пайплайн тест: поднимите приложение, отправьте запрос с заголовками на 90 процентов от заявленного лимита и проверьте код 200, затем на 120 процентов и проверьте код 431. Тест займет секунды и не даст случайно сузить лимит при обновлении фреймворка, когда меняются значения по умолчанию.

Работа с пулом прокси

Если вы используете несколько прокси-серверов или мобильный пул с ротацией, прогоните контрольный запрос на эхо-эндпоинт через каждый выход по HTTP и по HTTPS. Результаты сохраните в таблицу. Так вы выявите выходы с нестандартным поведением и сможете либо исключить их, либо отправлять через них только HTTPS-трафик, где обрезание невозможно.

FAQ

Чем 431 отличается от 494, если по сути оба про большие заголовки?

431 это стандартный код из спецификации HTTP, его понимают все клиенты и инструменты мониторинга. 494 это внутренний код nginx, который по умолчанию наружу превращается в 400 с текстом Request Header Or Cookie Too Large. Для пользователя разницы нет, а для диагностики 494 в логах или в error_page однозначно указывает на nginx как источник.

Можно ли просто поставить очень большой лимит и забыть?

Технически да, но так вы увеличите потребление памяти на каждое соединение и упростите атаки с гигантскими заголовками. Кроме того, лимиты CDN и браузеров вы не контролируете, и проблема просто переедет туда. Правильный порядок: сначала уменьшить куки, потом выставить умеренный лимит с запасом.

Почему в инкогнито все работает, а в обычном режиме ошибка?

В инкогнито нет накопленных куки. Это почти стопроцентный признак, что причина в размере заголовка Cookie у конкретного пользователя. Очистка куки для домена решит проблему разово, а шаг 5 решит ее навсегда.

Как измерить размер заголовков, если нет доступа к серверу?

Используйте панель разработчика: вкладка Application показывает размер каждой куки, а команда document.cookie.length в консоли дает общую длину доступных скриптам куки. Для точного порога отказа отправляйте curl с искусственно большим заголовком и смотрите код ответа.

Мой прокси может обрезать заголовки в HTTPS-запросах?

Нет. При HTTPS через прокси используется метод CONNECT, и прокси передает шифрованный поток байтов, не видя его содержимого. Обрезать или изменить заголовки внутри он физически не может. А вот для обычных HTTP-запросов прокси разбирает заголовки сам, и здесь возможны и лимиты, и обрезание.

Как понять, что заголовок обрезан, если ошибки нет?

Поднимите эхо-эндпоинт из шага 4, отправьте заголовок известной длины с маркерами позиции и сравните длину и хэш полученного значения с отправленным. Расхождение покажет и факт обрезания, и позицию среза.

Nginx пропускает, а приложение на Node.js отвечает 431. Что делать?

Поднять лимит Node.js флагом --max-http-header-size или параметром maxHeaderSize в createServer, а затем привести лимит nginx к тому же или меньшему значению, чтобы отказ происходил на внешнем слое с понятной страницей.

Что важнее ограничить: размер одного заголовка или общий размер?

И то, и другое. Общий размер защищает память, а лимит на одно поле защищает парсеры. У nginx оба лимита выводятся из large_client_header_buffers: размер буфера это лимит на строку, а число буферов умноженное на размер это общий лимит.

Стоит ли перехватывать 431 на клиенте и автоматически чистить куки?

Для собственного сайта это отличный прием: при получении 431 или 400 с нужным текстом фронтенд удаляет заведомо необязательные куки и повторяет запрос. Не удаляйте куки авторизации без согласия пользователя и обязательно логируйте такие события, чтобы устранить корень проблемы.

Как убедиться, что новая версия фреймворка не изменила лимит по умолчанию?

Держите синтетическую проверку из шага 7 и тест в CI из раздела дополнительных возможностей. Оба отправляют запросы на границе лимита и сразу покажут, если порог сдвинулся в любую сторону.

Заключение

Давайте подведем итог того, что вы сделали. Вы научились воспроизводить ошибку и отличать 431, 494 и его публичное обличье в виде 400 по подписи ответа. Вы измерили реальный размер заголовков и куки и нашли порог отказа бинарным поиском через curl. Вы определили, какой узел цепочки отвечает за отказ, и отделили эту проблему от кодов прокси-слоя вроде 407, 502 и 504, оставив себе полезный маркер про upstream sent too big header. С помощью эхо-эндпоинта вы поймали или исключили тихое обрезание, которое не оставляет следов в логах. Затем вы сократили куки, вынесли API на чистый домен, согласовали лимиты на nginx, Apache, Node.js, Tomcat, Gunicorn и HAProxy, сделали отказы явными и подключили мониторинг.

Что делать дальше. В ближайшую неделю понаблюдайте за метрикой размера запросов и за счетчиком 431: они покажут, не осталось ли источника роста куки. Заведите правило для команды: любая новая кука проходит ревью с вопросами о размере, домене и пути. Если проект использует сессии в куке в виде сериализованного состояния, запланируйте переезд на серверное хранение с коротким идентификатором.

Куда развиваться. Следующий уровень это глубокое понимание сжатия заголовков в HTTP/2 и HTTP/3, тонкая настройка буферов под нагрузку и построение прозрачного слоя наблюдаемости, где размер каждого запроса виден в трассировке. Полезно также изучить, как ведут себя лимиты при работе через разные типы прокси и балансировщиков, и собрать собственную таблицу порогов для инфраструктуры, с которой вы работаете. Инструменты, собранные в этом гайде, включая эхо-эндпоинт и цикл curl, останутся с вами и будут экономить часы при каждом следующем странном отказе. У вас все получилось, и теперь эта категория проблем перестала быть загадкой.