Fix SearXNG Rate Limits and 429 Errors
SearXNG 429 errors come from the local limiter or an upstream image request. Read the log, check API counters, and fix the right source of the block.
Why SearXNG returns 429 errors
A self-hosted SearXNG instance hits rate limits in two unrelated places, and the rate limit you need to fix is usually not the one you assume. Both local limiting and an upstream image request can produce a 429. The first is local: SearXNG's own limiter decided a request came from a bot and answered Too Many Requests with status 429. The /image endpoint also forwards upstream error statuses, including 429. The second is upstream: a search engine refused your server's IP address. SearXNG marks that engine as unresponsive and suspends it, and your users still get a normal results page with things missing, not a 429.
The two cases share no fix. The limiter is yours, so you can change it. Upstream blocking happens on the engine's side, so changing your local limiter will not lift it. The log tells you which one you have in about a minute, so start there.
This guide assumes the container install described in a self-hosted SearXNG instance on your own VPS. Every setting name below comes from current upstream documentation and source, checked on 16 November 2026.
Read the log before you change a setting
Reproduce the problem with a log window open. In the upstream compose file the SearXNG service is named core (its container is named searxng-core), and docker compose commands take the service name:
cd ./searxng/
docker compose logs -f coreLimiter messages come from loggers named searx.limiter and searx.botdetection and they name the client network. A blocklist hit reads BLOCK 203.0.113.10/32: matched BLOCKLIST, and an allowlist hit reads PASS 203.0.113.10/32: matched PASSLIST, each followed by the list entry that matched. If the limiter cannot initialize its counter store, the log says The limiter requires Valkey, please consult the documentation, which means the limiter has not been installed.
Each individual bot check is logged at debug level, so you will not see it by default. Turn debug on for one test in settings.yml:
general:
debug: trueThe log then adds lines shaped like BLOCK 203.0.113.10/32: missing HTTP header Accept-Language, naming the client network and the header that failed. Turn it off again afterwards, because upstream tells you not to run a deployed instance with debug on.
Engine failures look nothing like that. They name an engine instead of an IP; the detailed timeout message is logged at debug level, while the search thread's engine timeout message is logged at error level:
HTTP requests timeout (search duration : 3.1 s, timeout: 3.0 s)There is also a page for this. With enable_metrics left at its default of true, your instance records engine errors at /stats/errors, and /preferences lists which engines are currently answering. An entry in /stats/errors identifies an engine failure, but missing searx.limiter lines do not rule out a limiter block because individual bot checks use searx.botdetection at debug level.
Pin the version before you debug anything
The upstream container setup is two files.
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 .envThe compose file pulls docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}. An unset variable means latest, and latest means the instance changes under you on the next docker compose pull, so a setting that worked last week can stop matching the code that reads it. SearXNG tags carry a date and a commit. The example tag in the upstream .env.example as of October 2026 is 2026.3.25-541c6c3cb, so set a real one in .env:
SEARXNG_VERSION=2026.3.25-541c6c3cbCheck the published tags and pin the release you actually tested, then debug against a fixed target. The same .env file can hold your secret key through SEARXNG_SECRET, so read how env files and secrets work in Docker Compose before you commit that directory anywhere.
The limiter needs Valkey, or it does not run
The limiter counts requests per client, and those counts have to be shared across worker processes. That store is Valkey, the maintained fork of Redis. Older SearXNG guides call this setting redis:. Current releases read valkey:, so copy the key name from the current documentation rather than from an older post. Some of those pages reach back further still and describe Searx rather than SearXNG, which is a different codebase with a different limiter, so work out which of the two projects a page was written for before you copy a config block out of it.
use_default_settings: true
server:
secret_key: "change-this-value"
limiter: true
public_instance: false
valkey:
url: valkey://searxng-valkey:6379/0The upstream compose file already runs a valkey service on the docker.io/valkey/valkey:9-alpine image, in a container named searxng-valkey, so that host name resolves inside the compose network. The same value can be set with the SEARXNG_VALKEY_URL environment variable, and a Unix socket URL (unix:///path/to/socket.sock?db=0) works when SearXNG and Valkey share a host.
What happens when the store is missing depends on one other key. With public_instance: false, the limiter logs the Valkey error and gives up, so the instance keeps serving with no rate limiting at all. With public_instance: true, the process calls sys.exit(1) instead, rather than serving a public instance without bot protection. A container that restarts in a loop after this Valkey initialization error needs its Valkey connection fixed.
What the limiter actually counts
The data behind this chart
[
{
"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"
}
]With link-token checking disabled, a client gets 15 requests inside a 20 second burst window and 150 inside a 10 minute window. With it enabled, a client passing the link-token check bypasses both counters; a suspicious client gets 2 per burst window. The last row is the harshest: after 3 flagged requests inside a 30 day window, that address is redirected to the start page instead of searching, and the log says BLOCK: too many request from ... in SUSPICIOUS_IP_WINDOW (redirect to /). Passing the link-token check clears that client's suspicious-request counter.
These numbers are constants in searx/botdetection/ip_limit.py. They are not settings, and limiter.toml does not expose them, so changing them means editing the source. What /etc/searxng/limiter.toml does control is the address prefixes used to group clients, the list of trusted proxies, the optional link token check, and the pass and block lists.
The flagged rows only apply when that link token check is on, either through link_token = true in limiter.toml or because public_instance: true switches it on for you. A client then counts as suspicious until it loads a stylesheet whose URL carries a random token. With the link token off, the default, every client reaching these counters gets the normal rows.
The header checks are stricter, because they do not flag anything: a request that fails one is refused with 429 on the spot. Each check is a module in searx/botdetection/, and the debug log line names the header that failed:
http_accept: theAcceptheader does not containtext/html.http_accept_encoding: theAccept-Encodingheader names neithergzipnordeflate.http_accept_language: there is noAccept-Languageheader.http_user_agent: theUser-Agentis missing or matches a known bot pattern.http_sec_fetch: theSec-Fetch-*headers are not what a browser sends. This one only runs on HTTPS requests from browser versions known to send them, and it redirects to the start page rather than answering 429. In current source only an invalidSec-Fetch-Modeactually triggers that redirect: an invalidSec-Fetch-SiteorSec-Fetch-Destis logged at debug level, but the request goes through.
A browser sends all of these. A plain curl call sends almost none of them, so a hand-written test request is refused on its first try while the same search works in a browser tab. That is why "it works in my browser, but my script gets 429" is the normal result rather than a mystery.
Behind a reverse proxy the limiter blocks everyone at once
This is the most common way to break a working instance. SearXNG takes the client address from the first untrusted IP in X-Forwarded-For, falls back to X-Real-IP, and falls back again to the address that opened the connection. Whether those headers are believed at all is decided by trusted_proxies in limiter.toml. The botdetection documentation says trusted_proxies is ignored when only X-Real-IP is set, but the code in searx/botdetection/trusted_proxies.py, checked on 16 November 2026, drops both headers whenever the connecting address is not trusted, so sending only X-Real-IP does not get you around the list.
If your proxy's address is not in that list, the headers are ignored and every visitor arrives wearing the proxy's address. They then share one counter, so with link-token checking disabled, the whole site is blocked together once the total crosses 150 requests in 10 minutes. With link-token checking enabled, suspicious clients share the stricter counters, while a client passing the check bypasses the burst and long-window counters.
Trusting too much is worse. If a public range is listed, a visitor connecting from that trusted range can send their own X-Forwarded-For header and pick a fresh identity for every request. List only the address your own proxy connects from. In Docker that is usually a bridge network inside 172.16.0.0/12, and that line ships commented out.
[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48
trusted_proxies = [
'127.0.0.0/8',
'::1',
'172.16.0.0/12',
]The proxy has to send the headers as well. Nginx does not add X-Forwarded-Proto, X-Real-IP or X-Forwarded-For on its own:
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 and Traefik set the forwarded headers for you, so with those you only need the trusted_proxies half of the job. The trade-offs are covered in choosing a reverse proxy for a self-hosted service. To verify either setup, turn debug on, search once from your phone on mobile data, and confirm the network in the log line is your phone's address rather than the proxy's.
Your agent's API limit depends on the request
The JSON output is disabled by default, so an agent needs it added:
search:
formats:
- html
- jsonNow read the chart row again. A /search request with a URL query parameter format other than html is counted in its own window: 4 requests per 1 hour, per client network. The API supports POST form parameters, but a non-HTML format supplied solely in POST form data does not increment this API counter; other limiter checks still apply. Passing the link-token check does not bypass the API counter, which runs first. A research agent using ?format=json burns that in one task, and every call after it returns 429. The number itself is a constant in the source, so you cannot raise it from config, but you do not have to: you can take the agent's address out of the count entirely.
The clean fix is to tell the limiter that this client is not a stranger. Add its address to the pass list in limiter.toml:
[botdetection.ip_lists]
block_ip = []
pass_ip = [
'10.8.0.0/24',
]
pass_searxng_org = truepass_ip has priority over every other method, and upstream's own comment in limiter.toml says an address on that list has unrestricted access. So an allowlisted client is not held to the four request window, it skips the header checks too, and a bare curl call works. Keep the range as small as you can, and prefer a VPN subnet or a container network over anything routable. Pointing the agent directly at the container on an internal network does not bypass SearXNG's own limiter; allowlist the client address SearXNG actually sees. Wiring that up is covered in giving an AI agent a SearXNG search skill.
The option to avoid is pointing an agent at a public instance somebody else runs. Automated traffic through SearXNG risks getting that instance blocked by upstream engines.
When the engines block you instead
The data behind this chart
[
{
"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"
}
]When an engine answers with its own 429 or with a CAPTCHA page, SearXNG raises a named exception and stops asking that engine for a while. Your visitors never see that engine-search 429: the search still returns a normal results page, just without that engine. A too-many-requests answer suspends it for 180 seconds, and an access-denied answer for 3 minutes as well. A plain CAPTCHA suspends it for 1 hour. A CAPTCHA served through Cloudflare suspends it for 15 days, the longest default in the list. Which of the three CAPTCHA rows you landed on changes what is worth trying next, and the CAPTCHA errors have their own set of fixes once you know which exception your instance recorded.
These are the values in the searx/settings.yml that ships with SearXNG, checked on 16 November 2026. The settings documentation still prints older, longer values (one hour for too many requests, one day for access denied and for a plain CAPTCHA), so trust the file your instance actually loads over a page that quotes it.
Ordinary failures use different settings. A timeout or a failed connection suspends the engine for search.ban_time_on_fail seconds, 5 by default, and never longer than search.max_ban_time_on_fail, 120 by default. A parse error is recorded in /stats/errors but does not suspend the engine at all. So a slow engine recovers on its own within seconds, while an engine that served a CAPTCHA is gone for an hour or more. That difference explains a symptom people report as random: results are fine, then one engine's results vanish for an hour at a time.
Timeouts are worth fixing before you blame anyone. The default request_timeout is 3.0 seconds, which can still be tight for a small VPS sitting far from an engine's nearest edge server.
outgoing:
request_timeout: 3.5
max_request_timeout: 10.0
engines:
- name: bing
timeout: 5.0request_timeout is the default for every engine, max_request_timeout is the ceiling, and a single engine can carry its own timeout. Raising these trades page latency for fewer failures, so move in half seconds and watch /stats/errors rather than jumping straight to 10.
For an engine that is genuinely blocking your address, remove it. Suspended engines are skipped until their suspension expires; keeping an engine that repeatedly blocks you adds failed retries when it becomes eligible again.
use_default_settings:
engines:
remove:
- googleApply changes with docker compose restart core, then run a few searches and reload /stats/errors. Check that the searches return results as well as checking for recorded errors.
A datacentre IP can be treated as a bot
Google blocks networks it identifies as sending automated traffic, including shared VPN networks. No local limiter setting lifts that upstream block. The engines seeing your server instead of the person typing the query is also the whole of the privacy trade you made by self-hosting, and how much SearXNG actually hides is worth reading before you assume it covers more.
What you can change is which engines you ask and whether your instance is listed publicly. SearXNG can route engine requests through a proxy with outgoing.proxies or outgoing.using_tor_proxy, which moves the traffic to a different address. A different exit address does not guarantee access: Google also blocks some shared VPN and tunnel services because of automated traffic from their users.
Watch the instance so you find out first
SearXNG answers on its port even when every engine is suspended, so an uptime check that only watches the status code stays green while the instance returns nothing. Check the content instead: request a real search and match a word you expect in the response body. Uptime Kuma keyword monitoring does exactly that with no extra tooling. Watch /stats/errors after every version bump too, because engines change their HTML and a parser breaks with no rate limit involved.
FAQ
Why does SearXNG return 429 to every visitor after I put it behind a reverse proxy?
Because the limiter is counting the proxy as the client. SearXNG only reads X-Forwarded-For when the connecting address is listed in trusted_proxies in /etc/searxng/limiter.toml. If it is not listed, every visitor shares one counter; with link-token checking disabled, they all cross the 150 requests per 10 minutes line together. With link-token checking enabled, suspicious clients share stricter counters, while clients passing the check bypass the burst and long-window counters. Add the address your proxy connects from, which in Docker is usually the bridge range 172.16.0.0/12, and make sure the proxy sends X-Real-IP and X-Forwarded-For. Never list a range you do not control, because a client connecting from a trusted range can set that header and choose a new identity for every request.
How many API requests per hour does the SearXNG limiter allow?
Four per client network per hour for /search requests whose URL query parameter format is not html. A non-HTML format supplied solely in POST form data does not increment that API counter, although other limiter checks still apply. That number is set in searx/botdetection/ip_limit.py rather than in limiter.toml, so it cannot be raised from config. An agent or a script using ?format=json passes it in one task. An address listed in pass_ip in limiter.toml gets unrestricted access and is not counted at all, so add the client's address there. Connecting over an internal network alone does not bypass SearXNG's limiter.
Why do my search results come back empty with no 429 error?
The engines are refusing your server, not your users. Open /stats/errors on your own instance: it names each engine that failed and why, and a CAPTCHA or access-denied entry means that engine blocked your server's IP address. SearXNG then suspends the engine, for three minutes after a too-many-requests or access-denied answer, for an hour after a plain CAPTCHA, and for a week or more after a reCAPTCHA or Cloudflare CAPTCHA. No local limiter setting lifts an upstream block, so remove the engines that block your address and keep the ones that answer.
Should I enable the limiter on a private instance?
If nothing reaches the instance except you, leave limiter: false. It adds a Valkey dependency and it blocks your own scripts, and it protects against traffic you do not have. Enable it the moment the instance gets a public address, together with public_instance: true. That pair is deliberate: with public_instance: true and no working Valkey at initialization, the process exits with status 1 instead of running unprotected.