Как исправить ошибки 429 и лимиты SearXNG
Ошибка `429 Too Many Requests` в SearXNG может исходить от local limiter или upstream для `/image`. Проверьте журнал и API-счётчики, чтобы выбрать нужное исправление.
Почему SearXNG возвращает ошибки 429
Экземпляр SearXNG, размещённый на собственном сервере, может столкнуться с ограничениями частоты запросов в двух независимых местах. Обычно исправлять нужно не то ограничение, о котором вы думаете в первую очередь. И локальное ограничение, и запрос изображения к upstream могут привести к ответу 429. В первом случае ограничение действует локально: собственный limiter SearXNG решил, что запрос поступил от бота, и вернул Too Many Requests со статусом 429. Endpoint /image также передаёт статусы ошибок upstream, включая 429. Во втором случае ограничение действует на стороне upstream: поисковая система отклонила IP-адрес вашего сервера. SearXNG помечает эту поисковую систему как не отвечающую и приостанавливает её использование. При этом пользователи по-прежнему получают обычную страницу результатов, но часть результатов отсутствует, а ответ 429 не возвращается.
Для этих двух случаев нужны разные исправления. Локальное ограничение действует на вашей стороне, поэтому вы можете изменить его. Блокировка на стороне upstream происходит на стороне поисковой системы, поэтому изменение локального limiter не снимет её. По журналу примерно за минуту можно определить, с каким случаем вы столкнулись. Начните с проверки журнала.
В этом руководстве предполагается установка в контейнере, описанная в разделе экземпляр SearXNG на собственном VPS. Все приведённые ниже имена параметров взяты из актуальной документации и исходного кода upstream. Проверка выполнена 16 November 2026.
Сначала изучите журнал, а затем изменяйте настройку
Воспроизведите проблему, предварительно открыв окно с журналом. В upstream-файле Compose сервис SearXNG называется core, а его контейнер — searxng-core. Команды docker compose используют имя сервиса:
cd ./searxng/
docker compose logs -f coreСообщения limiter поступают от логгеров с именами searx.limiter и searx.botdetection и содержат имя клиентской сети. При срабатывании blocklist появляется сообщение BLOCK 203.0.113.10/32: matched BLOCKLIST, а при срабатывании allowlist — PASS 203.0.113.10/32: matched PASSLIST. После него указывается совпавшая запись списка. Если limiter не может инициализировать хранилище счётчиков, в журнал записывается The limiter requires Valkey, please consult the documentation. Это означает, что limiter не установлен.
Каждая отдельная проверка бота записывается на уровне debug, поэтому по умолчанию эти записи не отображаются. Включите debug на время одной проверки в settings.yml:
general:
debug: trueПосле этого в журнале появятся строки вида BLOCK 203.0.113.10/32: missing HTTP header Accept-Language. В них указываются клиентская сеть и заголовок, не прошедший проверку. После проверки снова отключите debug. Upstream не рекомендует запускать развернутый экземпляр с включённым debug.
Ошибки engine выглядят иначе. В них указывается engine, а не IP-адрес. Подробное сообщение о тайм-ауте записывается на уровне debug, а сообщение поискового потока engine timeout — на уровне error:
HTTP requests timeout (search duration : 3.1 s, timeout: 3.0 s)Для этого также предусмотрена отдельная страница. Если enable_metrics оставлен со значением по умолчанию true, экземпляр записывает ошибки engine в /stats/errors, а в /preferences отображается список engine, которые в данный момент отвечают. Запись в /stats/errors указывает на ошибку engine, но отсутствие строк searx.limiter не исключает блокировку limiter, поскольку отдельные проверки бота используют searx.botdetection на уровне debug.
Зафиксируйте версию до начала отладки
Исходная конфигурация контейнера состоит из двух файлов.
mkdir -p ./searxng/core-config/
cd ./searxng/
curl -fsSL \
-O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
-O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
cp -i .env.example .envФайл Compose загружает docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}. Если переменная не задана, используется latest. Значение latest означает, что при следующем docker compose pull экземпляр изменится без вашего контроля. Поэтому настройка, которая работала на прошлой неделе, может перестать соответствовать коду, который её обрабатывает. Теги SearXNG содержат дату и commit. В примере тегом в исходном .env.example по состоянию на October 2026 является 2026.3.25-541c6c3cb. Укажите фактический тег в .env:
SEARXNG_VERSION=2026.3.25-541c6c3cbПроверьте опубликованные теги и зафиксируйте релиз, который вы действительно протестировали. Затем выполняйте отладку с неизменяемой целевой версией. В том же файле .env секретный ключ можно хранить через SEARXNG_SECRET. Перед тем как добавлять этот каталог в систему контроля версий или размещать его где-либо, прочитайте как работают env-файлы и секреты в Docker Compose.
Лимитатору нужен Valkey, иначе он не запускается
Лимитатор считает запросы от каждого клиента, и эти счётчики нужно совместно использовать между рабочими процессами. Для этого применяется Valkey — поддерживаемый форк Redis. В старых руководствах по SearXNG этот параметр обозначен как redis:. Текущие версии читают valkey:, поэтому имя ключа нужно брать из актуальной документации, а не из старой публикации. Некоторые такие страницы относятся к ещё более раннему периоду и описывают Searx, а не SearXNG. Это другой код с другим лимитатором. Поэтому перед копированием блока конфигурации из такой страницы определите, для какого из двух проектов она написана.
use_default_settings: true
server:
secret_key: "change-this-value"
limiter: true
public_instance: false
valkey:
url: valkey://searxng-valkey:6379/0В исходном compose-файле уже запускается сервис valkey на образе docker.io/valkey/valkey:9-alpine, в контейнере с именем searxng-valkey. Поэтому это имя хоста разрешается внутри compose-сети. То же значение можно задать через переменную окружения SEARXNG_VALKEY_URL. URL Unix-сокета (unix:///path/to/socket.sock?db=0) работает, если SearXNG и Valkey находятся на одном хосте.
Поведение при отсутствии хранилища зависит ещё от одного ключа. При public_instance: false лимитатор записывает ошибку Valkey в журнал и прекращает работу. Поэтому экземпляр продолжает обслуживать запросы вообще без ограничения частоты. При public_instance: true процесс вместо этого вызывает sys.exit(1), а не запускает общедоступный экземпляр без защиты от ботов. Если контейнер после этой ошибки инициализации Valkey перезапускается по кругу, нужно исправить подключение к Valkey.
Что на самом деле учитывает ограничитель
Данные, на которых построен график
[
{
"label": "Burst, link token off",
"max_requests": 15,
"window": "20 seconds"
},
{
"label": "Burst, flagged client",
"max_requests": 2,
"window": "20 seconds"
},
{
"label": "Sustained, link token off",
"max_requests": 150,
"window": "10 minutes"
},
{
"label": "Sustained, flagged client",
"max_requests": 10,
"window": "10 minutes"
},
{
"label": "Non-HTML format in URL query",
"max_requests": 4,
"window": "1 hour"
},
{
"label": "Flagged requests before block",
"max_requests": 3,
"window": "30 days"
}
]При отключённой проверке link token клиент получает 15 запросов в течение 20-секундного окна всплеска и 150 запросов в течение 10-минутного окна. При включённой проверке клиент, прошедший проверку link token, не учитывается ни в одном из двух счётчиков. Для подозрительного клиента действует ограничение 2 запросов на одно окно всплеска. Последняя строка является самой строгой: после 3 помеченных запросов в течение 30-дневного окна этот адрес перенаправляется на стартовую страницу вместо выполнения поиска, а в журнале появляется сообщение BLOCK: too many request from ... in SUSPICIOUS_IP_WINDOW (redirect to /). Успешная проверка link token обнуляет счётчик подозрительных запросов этого клиента.
Эти числа заданы константами в searx/botdetection/ip_limit.py. Это не параметры настройки, а limiter.toml не предоставляет для них отдельного интерфейса. Поэтому для их изменения нужно редактировать исходный код. Настраивать через /etc/searxng/limiter.toml можно префиксы адресов, по которым группируются клиенты, список доверенных прокси, необязательную проверку link token, а также списки разрешённых и заблокированных адресов.
Строки для подозрительных клиентов применяются только при включённой проверке link token. Её можно включить через link_token = true в limiter.toml или с помощью public_instance: true. После этого клиент считается подозрительным, пока не загрузит таблицу стилей, URL которой содержит случайный токен. Если link token отключён, как задано по умолчанию, для всех клиентов, достигших этих счётчиков, применяются обычные строки.
Проверки заголовков строже, поскольку они ничего не помечают: запрос, не прошедший одну из них, сразу отклоняется с кодом 429. Каждая проверка является модулем в searx/botdetection/, а строка отладочного журнала содержит имя заголовка, который не прошёл проверку:
http_accept: заголовокAcceptне содержитtext/html.http_accept_encoding: в заголовкеAccept-Encodingне указаны ниgzip, ниdeflate.http_accept_language: заголовокAccept-Languageотсутствует.http_user_agent: заголовокUser-Agentотсутствует или соответствует известному шаблону бота.http_sec_fetch: заголовкиSec-Fetch-*отличаются от тех, которые отправляет браузер. Эта проверка выполняется только для HTTPS-запросов от версий браузеров, которые, как известно, отправляют такие заголовки. Вместо ответа 429 запрос перенаправляется на стартовую страницу. В текущем исходном коде это перенаправление выполняется только при недопустимомSec-Fetch-Mode. НедопустимыеSec-Fetch-SiteилиSec-Fetch-Destзаписываются в журнал на уровне debug, но запрос продолжается.
Браузер отправляет все эти заголовки. Обычный вызов curl не отправляет почти ни одного из них, поэтому вручную сформированный тестовый запрос отклоняется уже при первой попытке, хотя тот же поиск в открытой вкладке браузера выполняется успешно. Поэтому результат «в браузере работает, а мой скрипт получает 429» является обычным, а не загадочным.
За reverse proxy лимитер блокирует всех сразу
Это самый распространённый способ сломать работающий экземпляр. SearXNG получает адрес клиента из первого недоверенного IP-адреса в X-Forwarded-For, затем использует X-Real-IP, а в последнюю очередь — адрес, с которого установлено соединение. Доверять ли вообще этим заголовкам, определяет trusted_proxies в limiter.toml. В документации botdetection указано, что trusted_proxies игнорируется, если задан только X-Real-IP, но код в searx/botdetection/trusted_proxies.py, проверенный 16 November 2026, отбрасывает оба заголовка, если адрес, с которого установлено соединение, не является доверенным. Поэтому передача только X-Real-IP не позволяет обойти этот список.
Если адрес вашего proxy не входит в этот список, заголовки игнорируются, и каждый посетитель определяется адресом proxy. Все посетители используют один счётчик. Поэтому при отключённой проверке link-token весь сайт блокируется одновременно, как только общее число запросов превышает 150 за 10 минут. При включённой проверке link-token подозрительные клиенты используют более строгие счётчики, а клиент, прошедший проверку, обходит счётчики burst и long-window.
Чрезмерное доверие создаёт ещё большую проблему. Если указать публичный диапазон, посетитель, подключившийся из этого доверенного диапазона, сможет передавать собственный заголовок X-Forwarded-For и выбирать новый идентификатор для каждого запроса. Указывайте только адрес, с которого подключается ваш proxy. В Docker это обычно сеть bridge внутри 172.16.0.0/12. Эта строка закомментирована в поставляемой конфигурации.
[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48
trusted_proxies = [
'127.0.0.0/8',
'::1',
'172.16.0.0/12',
]Proxy также должен передавать эти заголовки. Nginx не добавляет X-Forwarded-Proto, X-Real-IP или X-Forwarded-For автоматически:
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header Connection $http_connection;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}Caddy и Traefik задают forwarded headers автоматически. Поэтому для них нужно настроить только часть, относящуюся к trusted_proxies. Компромиссы рассмотрены в разделе выбор reverse proxy для self-hosted сервиса. Чтобы проверить любую из конфигураций, включите debug, один раз выполните поиск с телефона через мобильную сеть и убедитесь, что в строке журнала указан адрес телефона, а не адрес proxy.
Лимит API агента зависит от запроса
Вывод JSON по умолчанию отключён, поэтому его нужно добавить агенту:
search:
formats:
- html
- jsonТеперь снова изучите строку таблицы. Запрос /search с параметром URL-запроса format, отличным от html, учитывается в собственном окне: 4 запросов за 1 hour для каждой клиентской сети. API поддерживает параметры POST-формы, но формат, отличный от HTML, переданный только в данных POST-формы, не увеличивает этот счётчик API; остальные проверки ограничителя по-прежнему выполняются. Успешная проверка link-token не отменяет счётчик API, который обрабатывается первым. Исследовательский агент, использующий ?format=json, расходует этот лимит за одну задачу, после чего каждый вызов возвращает 429. Это число задано константой в исходном коде, поэтому изменить его через конфигурацию нельзя. Однако это не требуется: адрес агента можно полностью исключить из подсчёта.
Надёжное решение — сообщить ограничителю, что этот клиент является доверенным. Добавьте его адрес в список разрешённых в limiter.toml:
[botdetection.ip_lists]
block_ip = []
pass_ip = [
'10.8.0.0/24',
]
pass_searxng_org = truepass_ip имеет приоритет над всеми остальными методами, а собственный комментарий upstream в limiter.toml указывает, что адрес из этого списка получает неограниченный доступ. Поэтому на клиент из списка разрешённых не распространяется ограничение в четыре запроса за окно, он также пропускает проверки заголовков, и обычный вызов curl работает. Используйте как можно более узкий диапазон и отдавайте предпочтение подсети VPN или сети контейнеров, а не адресу, доступному для маршрутизации. Прямое обращение агента к контейнеру во внутренней сети не отменяет собственный ограничитель SearXNG; добавьте в список разрешённых адрес клиента, который фактически видит SearXNG. Настройка этого варианта описана в разделе как дать AI-агенту навык поиска через SearXNG.
Не следует направлять агента к общедоступному экземпляру, которым управляет другой человек. Автоматический трафик через SearXNG может привести к блокировке этого экземпляра upstream-поисковыми системами.
Если вас блокируют поисковые системы
Данные, на которых построен график
[
{
"label": "SearxEngineTooManyRequests",
"suspended_seconds": 180,
"roughly": "3 minutes"
},
{
"label": "SearxEngineAccessDenied",
"suspended_seconds": 180,
"roughly": "3 minutes"
},
{
"label": "SearxEngineCaptcha",
"suspended_seconds": 3600,
"roughly": "1 hour"
},
{
"label": "recaptcha_SearxEngineCaptcha",
"suspended_seconds": 604800,
"roughly": "7 days"
},
{
"label": "cf_SearxEngineCaptcha",
"suspended_seconds": 1296000,
"roughly": "15 days"
}
]Если поисковая система отвечает собственным кодом 429 или страницей с CAPTCHA, SearXNG вызывает именованное исключение и на некоторое время прекращает отправлять ей запросы. Посетители не увидят код 429 от этой поисковой системы: страница результатов всё равно откроется, но без результатов от неё. Ответ «слишком много запросов» приостанавливает её на 180 секунд, а ответ «доступ запрещён» — ещё на 3 minutes. Обычная CAPTCHA приостанавливает её на 1 hour. CAPTCHA, которую отдаёт Cloudflare, приостанавливает её на 15 days — это самый длительный срок по умолчанию в списке. От того, какую из трёх строк CAPTCHA вы получили, зависит, что стоит попробовать дальше. После того как вы узнаете, какое исключение записал ваш экземпляр, для ошибок CAPTCHA доступны отдельные способы исправления.
Это значения из searx/settings.yml, который поставляется с SearXNG. Они проверены 16 November 2026. В документации по настройке всё ещё указаны более старые и длительные значения: один час для слишком большого числа запросов, один день для отказа в доступе и обычной CAPTCHA. Поэтому ориентируйтесь на файл, который фактически загружает ваш экземпляр, а не на страницу с устаревшими значениями.
Для обычных сбоев используются другие настройки. Тайм-аут или ошибка подключения приостанавливают поисковую систему на search.ban_time_on_fail секунд, по умолчанию на 5, но не более чем на search.max_ban_time_on_fail, по умолчанию на 120. Ошибка разбора записывается в /stats/errors, но не приостанавливает поисковую систему. Поэтому медленная поисковая система автоматически восстанавливается через несколько секунд, а поисковая система, отдавшая CAPTCHA, недоступна час или дольше. Это объясняет симптом, который часто считают случайным: сначала результаты есть, а затем результаты одной поисковой системы исчезают примерно на час.
Прежде чем обвинять поисковую систему, проверьте тайм-ауты. Значение request_timeout по умолчанию равно 3.0 секунды. Для небольшого VPS, расположенного далеко от ближайшего edge-сервера поисковой системы, этого может быть недостаточно.
outgoing:
request_timeout: 3.5
max_request_timeout: 10.0
engines:
- name: bing
timeout: 5.0request_timeout — значение по умолчанию для каждой поисковой системы, max_request_timeout — максимальное значение, а отдельная поисковая система может иметь собственное значение timeout. Увеличение этих значений повышает задержку загрузки страницы, но уменьшает число сбоев. Увеличивайте их шагом в полсекунды и отслеживайте /stats/errors, а не переходите сразу к 10.
Если поисковая система действительно блокирует ваш адрес, удалите её. Приостановленные поисковые системы пропускаются до окончания срока приостановки. Если оставить поисковую систему, которая постоянно вас блокирует, после повторного допуска она снова создаст неудачные повторные попытки.
use_default_settings:
engines:
remove:
- googleПримените изменения с помощью docker compose restart core, затем выполните несколько поисковых запросов и перезагрузите /stats/errors. Убедитесь не только в отсутствии записанных ошибок, но и в том, что поисковые запросы возвращают результаты.
IP-адрес дата-центра может распознаваться как адрес бота
Google блокирует сети, с которых, по его данным, поступает автоматизированный трафик. Это касается и общих VPN-сетей. Ни одна локальная настройка ограничения скорости не снимает такую блокировку на стороне вышестоящего сервиса. То, что поисковые системы видят ваш сервер вместо человека, вводящего запрос, — основная особенность конфиденциальности при самостоятельном размещении сервиса. Перед тем как полагаться на более широкую защиту, прочитайте, что именно скрывает SearXNG.
Вы можете изменить список используемых поисковых систем и решить, будет ли ваш экземпляр опубликован. SearXNG может направлять запросы к поисковым системам через прокси с помощью outgoing.proxies или outgoing.using_tor_proxy. В этом случае трафик будет исходить с другого адреса. Другой адрес выхода не гарантирует доступ. Google также блокирует некоторые общие VPN- и туннельные сервисы из-за автоматизированного трафика от их пользователей.
Мониторинг экземпляра для оперативного реагирования
SearXNG отвечает на своем порту, даже если все движки приостановлены. Поэтому проверка доступности, которая отслеживает только код ответа, будет показывать статус «в сети», хотя экземпляр не выдает результатов. Проверяйте содержимое: выполните реальный поисковый запрос и ищите ожидаемое слово в теле ответа. Мониторинг ключевых слов в Uptime Kuma выполняет эту задачу без дополнительных инструментов. Также отслеживайте /stats/errors после каждого обновления версии, так как движки меняют HTML-разметку, что приводит к поломке парсеров вне зависимости от ограничений частоты запросов.
FAQ
Почему SearXNG возвращает 429 каждому посетителю после размещения за reverse proxy?
Потому что limiter считает proxy клиентом. SearXNG читает X-Forwarded-For только тогда, когда адрес подключения указан в trusted_proxies в /etc/searxng/limiter.toml. Если адрес не указан, все посетители используют один общий счётчик и при отключённой проверке link-token вместе превышают предел в 150 запросов за 10 минут. При включённой проверке link-token подозрительные клиенты используют более строгие счётчики, а клиенты, прошедшие проверку, не учитываются в burst-счётчиках и счётчиках длительного окна. Добавьте адрес, с которого подключается proxy. В Docker это обычно диапазон bridge 172.16.0.0/12. Убедитесь также, что proxy передаёт X-Real-IP и X-Forwarded-For. Не указывайте диапазон, которым вы не управляете: клиент из доверенного диапазона сможет установить этот заголовок и выбирать новую identity для каждого запроса.
Сколько API-запросов в час разрешает limiter SearXNG?
Четыре запроса в час от каждой сети клиента для запросов /search, в которых query-параметр URL format имеет значение, отличное от html. Формат, отличный от HTML, переданный только в данных POST-формы, не увеличивает этот API-счётчик, хотя остальные проверки limiter по-прежнему выполняются. Это значение задаётся в searx/botdetection/ip_limit.py, а не в limiter.toml, поэтому увеличить его через config нельзя. Агент или скрипт, использующий ?format=json, исчерпывает этот лимит в одной задаче. Адрес, указанный в pass_ip в limiter.toml, получает неограниченный доступ и вообще не учитывается, поэтому добавьте туда адрес клиента. Одно только подключение через внутреннюю сеть не отключает limiter SearXNG.
Почему результаты поиска возвращаются пустыми без ошибки 429?
Ваш server блокируют engines, а не пользователи. Откройте /stats/errors в своём экземпляре: там указаны каждый engine, который завершился ошибкой, и её причина. Запись о CAPTCHA или отказе в доступе означает, что этот engine заблокировал IP-адрес вашего server. Затем SearXNG приостанавливает engine на 3 минуты после ответа too-many-requests или отказа в доступе, на 1 час после обычной CAPTCHA и на неделю или дольше после reCAPTCHA или Cloudflare CAPTCHA. Локальная настройка limiter не снимает блокировку на стороне upstream. Удалите engines, которые блокируют ваш адрес, и оставьте те, которые отвечают.
Следует ли включать limiter в приватном экземпляре?
Если к экземпляру подключаетесь только вы, оставьте limiter: false. Он добавляет зависимость от Valkey и блокирует ваши собственные скрипты, хотя защищает от трафика, которого у вас нет. Включите его сразу после назначения экземпляру публичного адреса вместе с public_instance: true. Эта пара настроек выбрана намеренно: при public_instance: true и недоступном Valkey во время инициализации процесс завершается со статусом 1, а не запускается без защиты.