Як виправити 429 і ліміти запитів у SearXNG
Помилка SearXNG 429 виникає через локальний limiter або upstream-запит зображення. Перевірте журнал і лічильники API, щоб усунути правильне блокування.
Чому SearXNG повертає помилки 429
Self-hosted екземпляр SearXNG може досягти ліміту запитів у двох незалежних місцях. Зазвичай ліміт, який потрібно виправити, не той, про який ви думаєте. І локальне обмеження, і запит зображення до upstream можуть спричинити помилку 429. Перше обмеження локальне: власний limiter SearXNG визначив, що запит надійшов від бота, і повернув Too Many Requests зі статусом 429. Endpoint /image також передає статуси помилок upstream, зокрема 429. Другий випадок виникає на upstream: пошукова система відхилила IP-адресу вашого сервера. SearXNG позначає цю систему як недоступну й призупиняє її, а користувачі все одно отримують звичайну сторінку результатів, але без частини результатів, а не помилку 429.
Для цих двох випадків потрібні різні виправлення. Limiter належить вам, тому його можна змінити. Блокування на upstream відбувається на боці пошукової системи, тому зміна локального limiter не скасує його. Журнал приблизно за хвилину покаже, який саме випадок у вас, тому почніть із нього.
Цей посібник передбачає встановлення в контейнері, описане в self-hosted екземпляр 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-адресу. Детальне повідомлення про timeout записується на рівні 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.
Зафіксуйте версію, перш ніж щось налагоджувати
Конфігурація контейнера upstream складається з двох файлів.
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. Станом на жовтень 2026 року приклад тега у вихідному .env.example — 2026.3.25-541c6c3cb, тому вкажіть конкретне значення у .env:
SEARXNG_VERSION=2026.3.25-541c6c3cbПеревірте опубліковані теги та зафіксуйте реліз, який ви фактично протестували. Після цього налагоджуйте систему з фіксованою ціллю. Той самий файл .env може зберігати ваш secret key через SEARXNG_SECRET, тому перед розміщенням цього каталогу в будь-якому сховищі прочитайте як працюють env-файли та secrets у 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В upstream 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-секундного burst window і 150 запитів у межах 10-хвилинного вікна. Якщо перевірку ввімкнено, клієнт, який її проходить, обходить обидва лічильники; для підозрілого клієнта діє обмеження 2 запитів на burst window. Останній рядок є найсуворішим: після 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 вмикає її автоматично. Після цього клієнт вважається підозрілим, доки не завантажить stylesheet, URL якого містить випадковий token. Якщо link token вимкнено, що є типовою поведінкою, кожен клієнт, який досягає цих лічильників, обробляється за звичайними рядками.
Перевірки заголовків суворіші, оскільки вони нічого не позначають: запит, який не проходить одну з них, одразу відхиляється з кодом 429. Кожна перевірка є модулем у searx/botdetection/, а рядок debug-журналу містить назву заголовка, який не пройдено:
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 limiter блокує всіх одночасно
Це найпоширеніший спосіб зламати робочий інстанс. 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 не дає змоги обійти цей список.
Якщо адресу вашого проксі не внесено до цього списку, заголовки ігноруються, і кожен відвідувач приходить з адресою проксі. Усі вони використовують один лічильник, тому за вимкненої перевірки link-token весь сайт блокується одночасно, щойно загальна кількість запитів за 10 хвилин перевищує 150. За ввімкненої перевірки link-token підозрілі клієнти використовують суворіші лічильники, а клієнт, який проходить перевірку, обходить лічильники burst і довгого вікна.
Надмірна довіра небезпечніша. Якщо до списку внесено публічний діапазон, відвідувач із цього довіреного діапазону може передати власний заголовок X-Forwarded-For і вибирати нову ідентичність для кожного запиту. Додавайте лише адресу, з якої підключається ваш власний проксі. У Docker це зазвичай bridge network усередині 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',
]Проксі також має передавати ці заголовки. 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, один раз виконайте пошук із телефона через мобільну мережу та переконайтеся, що в рядку журналу вказано адресу телефона, а не адресу проксі.
Ліміт API вашого агента залежить від запиту
Виведення JSON типово вимкнене, тому агенту потрібно додати відповідний параметр:
search:
formats:
- html
- jsonТепер знову перегляньте рядок таблиці. Запит /search із параметром URL-запиту format, значення якого відрізняється від html, обліковується у власному вікні: 4 запитів за 1 hour, для кожної клієнтської мережі. API підтримує параметри POST-форми, але формат, відмінний від HTML, переданий лише в даних POST-форми, не збільшує цей лічильник API; інші перевірки limiter усе одно застосовуються. Проходження перевірки link-token не обходить лічильник API, оскільки він спрацьовує першим. Дослідницький агент, який використовує ?format=json, витрачає цей ліміт за одне завдання, а кожен наступний виклик повертає 429. Це число є константою у вихідному коді, тому змінити його в конфігурації не можна, але в цьому немає потреби: адресу агента можна повністю виключити з підрахунку.
Надійне рішення — повідомити limiter, що цей клієнт не є невідомим. Додайте його адресу до списку дозволених у limiter.toml:
[botdetection.ip_lists]
block_ip = []
pass_ip = [
'10.8.0.0/24',
]
pass_searxng_org = truepass_ip має пріоритет над усіма іншими методами, а власний коментар upstream у limiter.toml зазначає, що адреса з цього списку отримує необмежений доступ. Тому для клієнта зі списку дозволених не діє вікно з чотирма запитами, він також пропускає перевірки заголовків, а звичайний виклик curl працює. Обмежте діапазон до мінімально необхідного розміру та надавайте перевагу підмережі VPN або мережі контейнерів замість будь-якої маршрутизованої мережі. Безпосереднє підключення агента до контейнера через внутрішню мережу не обходить власний limiter SearXNG; додайте до списку дозволених адресу клієнта, яку фактично бачить SearXNG. Налаштування цього описано в розділі надання AI-агенту навички пошуку в SearXNG.
Не використовуйте варіант із підключенням агента до публічного instance, яким керує інша особа. Автоматичний трафік через SearXNG може призвести до блокування цього instance 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 листопада 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-мережі. Жоден локальний параметр обмеження не скасовує це блокування на стороні сервісу. Те, що пошукові системи бачать IP-адресу вашого сервера замість людини, яка вводить запит, також є суттю компромісу щодо конфіденційності під час self-hosting. Перед тим як вважати, що SearXNG приховує більше, варто прочитати наскільки багато насправді приховує SearXNG.
Ви можете змінити пошукові системи, до яких надсилаються запити, і вирішити, чи буде ваш екземпляр доступний публічно. SearXNG може спрямовувати запити до пошукових систем через проксі за допомогою outgoing.proxies або outgoing.using_tor_proxy. Це переносить трафік на іншу IP-адресу. Інша адреса виходу не гарантує доступ: 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. Не додавайте діапазон, яким не керуєте, оскільки клієнт із довіреного діапазону може встановити цей заголовок і вибирати нову ідентичність для кожного запиту.
Скільки API-запитів на годину дозволяє limiter SearXNG?
Чотири на кожну клієнтську мережу за годину для /search запитів, у яких URL-параметр запиту format не дорівнює html. Формат, відмінний від HTML, переданий лише у form data POST-запиту, не збільшує цей API-лічильник, хоча інші перевірки limiter все одно застосовуються. Це значення задається в searx/botdetection/ip_limit.py, а не в limiter.toml, тому його не можна збільшити через конфігурацію. Агент або скрипт, що використовує ?format=json, передає його в одному завданні. Адреса, зазначена в pass_ip у limiter.toml, отримує необмежений доступ і взагалі не враховується в лічильнику, тому додайте туди адресу клієнта. Саме підключення через внутрішню мережу не обходить limiter SearXNG.
Чому результати пошуку порожні, але помилки 429 немає?
Запити відхиляють engines на вашому сервері, а не у ваших користувачів. Відкрийте /stats/errors у власному екземплярі. Там указано кожен engine, який завершився помилкою, і її причину. Запис про CAPTCHA або відмову в доступі означає, що цей engine заблокував IP-адресу вашого сервера. Після відповіді too-many-requests або відмови в доступі SearXNG призупиняє engine на три хвилини, після звичайної CAPTCHA — на годину, а після reCAPTCHA або Cloudflare CAPTCHA — на тиждень або довше. Жодне локальне налаштування limiter не скасовує блокування на upstream. Тому видаліть engines, які блокують вашу адресу, і залиште ті, що відповідають.
Чи слід увімкнути limiter у приватному екземплярі?
Якщо до екземпляра підключаєтеся лише ви, залиште limiter: false. Він додає залежність від Valkey і блокує власні скрипти, хоча захищає від трафіку, якого у вас немає. Увімкніть його, щойно екземпляр отримає публічну адресу, разом із public_instance: true. Це поєднання є навмисним: якщо public_instance: true увімкнено, а Valkey недоступний під час ініціалізації, процес завершується зі статусом 1, а не запускається без захисту.