SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor

SearXNG 429: How to Fix Rate Limit Errors

SearXNG 429 fit come from local limiter or upstream /image request. Check log and API counters to know the block source, then apply the correct fix.

Why SearXNG dey return 429 errors

Self-hosted SearXNG instance fit hit rate limits for two unrelated places, and the rate limit wey you need fix usually no be the one wey you dey assume. Local limiting and upstream image request fit both produce 429. The first one na local: SearXNG own limiter decide say request come from bot, then answer Too Many Requests with status 429. The /image endpoint too dey forward upstream error statuses, including 429. The second one na upstream: search engine reject your server IP address. SearXNG mark that engine as unresponsive and suspend am, while your users still dey get normal results page with some results missing, not 429.

The two cases no get the same fix. The limiter na your own, so you fit change am. Upstream blocking dey happen for the engine side, so changing your local limiter no go remove am. The log go tell you which case you get within about one minute, so start there.

This guide assume say you use the container install wey dem describe for self-hosted SearXNG instance for your own VPS. Every setting name wey dey below come from current upstream documentation and source, checked on 16 November 2026.

Read log before you change any setting

Reproduce the problem while log window dey open. For the upstream compose file, dem name the SearXNG service core (the container name na searxng-core), and docker compose commands dey use the service name:

cd ./searxng/
docker compose logs -f core

Limiter messages dey come from loggers wey dem name searx.limiter and searx.botdetection, and dem dey show the client network. Blocklist hit dey read BLOCK 203.0.113.10/32: matched BLOCKLIST, while allowlist hit dey read PASS 203.0.113.10/32: matched PASSLIST. Each one dey follow with the list entry wey match. If limiter no fit initialize its counter store, log go show The limiter requires Valkey, please consult the documentation. This one mean say dem never install the limiter.

Dem dey log each bot check for debug level, so you no go see am by default. Turn debug on for one test inside settings.yml:

general:
  debug: true

Then log go add lines wey get this shape: BLOCK 203.0.113.10/32: missing HTTP header Accept-Language. The lines go name the client network and the header wey fail. Turn debug off again afterwards, because upstream talk say make you no run deployed instance with debug on.

Engine failures no dey look like that at all. Dem dey name an engine instead of an IP. Dem dey log the detailed timeout message for debug level, while the search thread's engine timeout message dey log for error level:

HTTP requests timeout (search duration : 3.1 s, timeout: 3.0 s)

Page dey available for this matter too. If you leave enable_metrics for its default value of true, your instance go record engine errors for /stats/errors, and /preferences go list the engines wey dey answer now. Entry inside /stats/errors dey identify engine failure. But if searx.limiter lines no dey, that one no rule out limiter block, because individual bot checks dey use searx.botdetection for debug level.

Pin version first before you debug anything

The upstream container setup na 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 .env

The compose file dey pull docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}. If variable no set, e mean latest, and latest mean say the instance go change under you for the next docker compose pull. So, setting wey work last week fit stop to match the code wey dey read am. SearXNG tags get date and commit. The example tag for the upstream .env.example as of October 2026 na 2026.3.25-541c6c3cb, so set real one for .env:

SEARXNG_VERSION=2026.3.25-541c6c3cb

Check the tags wey dem publish and pin the release wey you don test, then debug against fixed target. The same .env file fit keep your secret key through SEARXNG_SECRET, so read how env files and secrets dey work for Docker Compose before you commit that directory anywhere.

Limiter need Valkey, otherwise e no go run

Limiter dey count request from each client, and worker processes need share those counts. Na Valkey be the store, and na maintained fork of Redis e be. Older SearXNG guides dey call this setting redis:. Current releases dey read valkey:, so copy the key name from current documentation, no be from old post. Some of those pages even old pass and dey describe Searx instead of SearXNG. Dem be different codebases with different limiters, so confirm which of the two projects the page dey describe before you copy config block from am.

use_default_settings: true
server:
  secret_key: "change-this-value"
  limiter: true
  public_instance: false
valkey:
  url: valkey://searxng-valkey:6379/0

The upstream compose file already dey run one valkey service on the docker.io/valkey/valkey:9-alpine image, inside container wey dem name searxng-valkey. So that host name go resolve inside the compose network. You fit set the same value with SEARXNG_VALKEY_URL environment variable. A Unix socket URL (unix:///path/to/socket.sock?db=0) dey work when SearXNG and Valkey share the same host.

Wetin happen when the store no dey depend on one other key. With public_instance: false, limiter go log the Valkey error and stop, so the instance go continue serving without any rate limiting. With public_instance: true, the process go call sys.exit(1) instead, rather than serve public instance without bot protection. If container dey restart repeatedly after this Valkey initialization error, fix the Valkey connection.

Wetin the limiter dey actually count

ChartSearXNG limiter: requests allowed per client network, defaults in ip_limit.py
Di data wey dey behind dis 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"
  }
]

When link-token checking dey off, one client fit make 15 requests inside one 20 second burst window and 150 inside one 10 minute window. When e dey on, client wey pass the link-token check bypass both counters; suspicious client fit make 2 for each burst window. The last row na the strictest one: after 3 flagged requests inside one 30 day window, dem go redirect that address go start page instead of letting am search, and the log go talk 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 na constants for searx/botdetection/ip_limit.py. Dem no be settings, and limiter.toml no expose dem, so to change dem you need edit the source. Wetin /etc/searxng/limiter.toml control na the address prefixes wey e use 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 dey on, either through link_token = true for limiter.toml or because public_instance: true switch am on for you. Client then dey count as suspicious until e load one stylesheet wey URL carry random token. When link token dey off, wey be the default, every client wey reach these counters go get the normal rows.

The header checks strict pass, because dem no flag anything: request wey fail one of dem dey refused with 429 immediately. Each check na module for searx/botdetection/, and the debug log line dey name the header wey fail:

  • http_accept: the Accept header no contain text/html.
  • http_accept_encoding: the Accept-Encoding header no name either gzip or deflate.
  • http_accept_language: no Accept-Language header dey.
  • http_user_agent: the User-Agent dey miss or e match known bot pattern.
  • http_sec_fetch: the Sec-Fetch-* headers no be wetin browser dey send. This one only run for HTTPS requests from browser versions wey dem know say dey send dem, and e redirect go start page instead of answering 429. For current source, na only invalid Sec-Fetch-Mode dey actually trigger that redirect: invalid Sec-Fetch-Site or Sec-Fetch-Dest dey logged for debug level, but the request still go through.

Browser dey send all these ones. Plain curl call dey send almost none of dem, so hand-written test request go get refused on the first try, while the same search go work for browser tab. Na why “e dey work for my browser, but my script dey get 429” na the normal result, no be mystery.

Behind reverse proxy limiter dey block everybody at once

This na the most common way to break instance wey dey work. SearXNG dey take client address from the first untrusted IP for X-Forwarded-For, e fall back to X-Real-IP, then e fall back again to the address wey open the connection. Whether e go trust those headers at all na trusted_proxies for limiter.toml dey decide. The botdetection documentation talk say trusted_proxies dey ignored when na only X-Real-IP dem set, but the code for searx/botdetection/trusted_proxies.py, wey dem check on 16 November 2026, dey drop both headers whenever the connecting address no dey trusted. So, sending only X-Real-IP no go help you bypass the list.

If your proxy address no dey that list, dem go ignore the headers and every visitor go appear with the proxy address. Then dem go share one counter. So, when link-token checking dey disabled, the whole site go block together once the total pass 150 requests within 10 minutes. When link-token checking dey enabled, suspicious clients go share the stricter counters, while client wey pass the check go bypass the burst and long-window counters.

Trusting too much worse. If you list public range, visitor wey connect from that trusted range fit send their own X-Forwarded-For header and choose new identity for every request. List only the address wey your own proxy dey connect from. For Docker, na usually bridge network inside 172.16.0.0/12, and dem ship that line commented out.

[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48

trusted_proxies = [
  '127.0.0.0/8',
  '::1',
  '172.16.0.0/12',
]

The proxy too must send the headers. Nginx no dey add X-Forwarded-Proto, X-Real-IP or X-Forwarded-For by itself:

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 dey set the forwarded headers for you, so with dem, na only the trusted_proxies part of the work you need do. You fit read about the trade-offs for how to choose reverse proxy for self-hosted service. To verify either setup, turn debug on, search once from your phone with mobile data, and confirm say the network for the log line na your phone address, no be the proxy address.

Your agent API limit dey depend on the request

JSON output dey disabled by default, so agent need make you add am:

search:
  formats:
    - html
    - json

Now read the chart row again. A /search request wey get URL query parameter format wey no be html dey count for e own window: 4 requests per 1 hour, per client network. API support POST form parameters, but non-HTML format wey you supply only through POST form data no dey increase this API counter; other limiter checks still apply. Passing link-token check no bypass the API counter, because this counter dey run first. Research agent wey dey use ?format=json go use up that limit for one task, and every call after that go return 429. The number na constant for source code, so you no fit increase am from config, but you no need do that: you fit remove the agent address from the count completely.

The clean fix na to tell limiter say this client no be stranger. Add the address to the pass list for limiter.toml:

[botdetection.ip_lists]
block_ip = []

pass_ip = [
  '10.8.0.0/24',
]

pass_searxng_org = true

pass_ip get priority over every other method, and upstream own comment for limiter.toml talk say address for that list get unrestricted access. So allowlisted client no dey follow the four-request window, e skip the header checks too, and bare curl call go work. Keep the range as small as you fit, and prefer VPN subnet or container network instead of anything routable. Pointing the agent directly to the container for internal network no bypass SearXNG own limiter; allowlist the client address wey SearXNG actually dey see. How to give AI agent SearXNG search skill cover how to connect am.

The option wey you suppose avoid na pointing agent to public instance wey another person dey run. Automated traffic through SearXNG fit make upstream engines block that instance.

Engine dey block you instead

ChartHow long SearXNG suspends an engine, search.suspended_times defaults
Di data wey dey behind dis 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 engine answer with its own 429 or CAPTCHA page, SearXNG go raise named exception and stop to ask that engine for some time. Your visitors no go see that engine-search 429: search still go return normal results page, just without that engine. A too-many-requests answer go suspend am for 180 seconds, while access-denied answer go suspend am for 3 minutes too. Plain CAPTCHA go suspend am for 1 hour. CAPTCHA wey Cloudflare serve go suspend am for 15 days, wey be the longest default for the list. Which of the three CAPTCHA rows you reach go determine wetin make sense to try next, and the CAPTCHA errors get their own fixes once you know the exception wey your instance record.

These na the values inside searx/settings.yml wey ships with SearXNG, checked on 16 November 2026. The settings documentation still show older, longer values (one hour for too many requests, one day for access denied and plain CAPTCHA), so trust the file wey your instance actually loads instead of page wey quote am.

Ordinary failures dey use different settings. Timeout or failed connection go suspend the engine for search.ban_time_on_fail seconds, 5 by default, and e no go ever pass search.max_ban_time_on_fail, 120 by default. Parse error dey record inside /stats/errors but e no suspend the engine at all. So slow engine go recover by itself within seconds, while engine wey serve CAPTCHA don disappear for one hour or more. This difference explain one symptom people dey report as random: results dey okay, then one engine results go disappear for one hour at a time.

Timeouts dey worth fixing before you blame anybody. The default request_timeout na 3.0 seconds, and this fit still too short for small VPS wey far from the engine nearest edge server.

outgoing:
  request_timeout: 3.5
  max_request_timeout: 10.0
engines:
  - name: bing
    timeout: 5.0

request_timeout na the default for every engine, max_request_timeout na the ceiling, and one engine fit get its own timeout. If you raise these values, page latency go increase but failures go reduce, so increase am by half-second steps and monitor /stats/errors instead of jumping straight to 10.

For engine wey genuinely dey block your address, remove am. Suspended engines dey skipped until their suspension expire; if you keep engine wey dey repeatedly block you, e go add failed retries when e become eligible again.

use_default_settings:
  engines:
    remove:
      - google

Apply changes with docker compose restart core, then run some searches and reload /stats/errors. Check say the searches dey return results, and also check for recorded errors.

Datacentre IP fit dey treated like bot

Google dey block networks wey e identify say dem dey send automated traffic, including shared VPN networks. No local limiter setting fit remove that upstream block. The engines wey dey see your server instead of the person wey type the query na the main privacy trade-off for self-hosting. Read how much SearXNG really dey hide before you assume say e cover more.

Wetin you fit change na the engines wey you ask and whether your instance dey listed publicly. SearXNG fit route engine requests through proxy with outgoing.proxies or outgoing.using_tor_proxy, wey go move the traffic to another address. Another exit address no guarantee access. Google still dey block some shared VPN and tunnel services because their users dey generate automated traffic.

Watch the instance make you sabi problem first

SearXNG dey answer for its port even when all engines dey suspended, so uptime check wey only dey watch status code go still show green while the instance no dey return anything. Check the content instead: make request for real search and match word wey you expect inside response body. Uptime Kuma keyword monitoring dey do exactly that without any extra tool. Watch /stats/errors after every version bump too, because engines dey change their HTML and parser fit break even when no rate limit dey involved.

FAQ

Why SearXNG dey return 429 to every visitor after I put am behind reverse proxy?

Na because limiter dey count proxy as the client. SearXNG only reads X-Forwarded-For when the connecting address dey listed for trusted_proxies inside /etc/searxng/limiter.toml. If e no dey listed, every visitor dey share one counter; when link-token checking dey disabled, all of dem cross the 150 requests per 10 minutes limit together. When link-token checking dey enabled, suspicious clients dey share stricter counters, while clients wey pass the check bypass the burst and long-window counters. Add the address wey your proxy dey connect from. For Docker, na usually the bridge range 172.16.0.0/12. Make sure say proxy dey send X-Real-IP and X-Forwarded-For. Never list range wey you no control, because client wey connect from trusted range fit set that header and choose new identity for every request.

How many API requests per hour SearXNG limiter dey allow?

Four per client network per hour for /search requests wey their URL query parameter format no be html. Non-HTML format wey POST form data provide alone no dey increase that API counter, although other limiter checks still apply. That number dey set for searx/botdetection/ip_limit.py instead of limiter.toml, so you no fit increase am from config. Agent or script wey dey use ?format=json pass am for one task. Address wey dey listed for pass_ip inside limiter.toml get unrestricted access and no dey count at all, so add the client's address there. Connecting through internal network alone no bypass SearXNG limiter.

Why my search results dey come back empty without 429 error?

Na the engines dey reject your server, no be your users. Open /stats/errors for your own instance: e name each engine wey fail and explain why. CAPTCHA or access-denied entry mean say that engine block your server's IP address. SearXNG then suspend the engine for three minutes after too-many-requests or access-denied answer, for one hour after plain CAPTCHA, and for one week or more after reCAPTCHA or Cloudflare CAPTCHA. No local limiter setting fit remove upstream block, so remove engines wey block your address and keep the ones wey dey answer.

I suppose enable limiter for private instance?

If na only you dey reach the instance, leave limiter: false. E add Valkey dependency and e block your own scripts, while e dey protect against traffic wey you no get. Enable am as soon as the instance get public address, together with public_instance: true. That pair get deliberate reason: with public_instance: true and no working Valkey during initialization, the process go exit with status 1 instead of running without protection.

Dis article help you?