SSD Nodes Learn Hosting plans →
Guides Matt ConnorPar Matt Connor

Corriger les erreurs 429 et les rate limits SearXNG

SearXNG renvoie « Too Many Requests » ? Distinguez le limiter local d’un 429 upstream sur /image, puis vérifiez les logs et les compteurs API.

Pourquoi SearXNG renvoie des erreurs 429

Une instance SearXNG auto-hébergée peut atteindre des limites de débit à deux endroits sans rapport. La limite que vous devez corriger n’est généralement pas celle que vous pensez. Une limitation locale et une erreur lors d’une requête vers une image upstream peuvent toutes deux produire une réponse 429. Dans le premier cas, SearXNG applique sa propre limitation : il considère qu’une requête provient d’un bot et répond avec Too Many Requests avec le statut 429. Le endpoint /image transmet également les statuts d’erreur upstream, notamment 429. Dans le second cas, le problème vient de l’upstream : un moteur de recherche refuse l’adresse IP de votre serveur. SearXNG marque alors ce moteur comme non réactif et le suspend. Vos utilisateurs reçoivent toujours une page de résultats normale, mais certains résultats manquent ; ils ne reçoivent pas de réponse 429.

Ces deux cas n’ont pas le même correctif. La limitation vous appartient : vous pouvez la modifier. Le blocage upstream se produit du côté du moteur ; modifier votre limitation locale ne le supprimera pas. Les journaux indiquent lequel des deux cas vous concerne en environ une minute. Commencez donc par les consulter.

Ce guide suppose que vous avez effectué l’installation en conteneur décrite dans une instance SearXNG auto-hébergée sur votre propre VPS. Tous les noms de paramètres ci-dessous proviennent de la documentation et du code source upstream actuels, vérifiés le 16 novembre 2026.

Consultez le journal avant de modifier un paramètre

Reproduisez le problème avec une fenêtre de journal ouverte. Dans le fichier compose amont, le service SearXNG s’appelle core (son conteneur s’appelle searxng-core), et les commandes docker compose utilisent le nom du service :

cd ./searxng/
docker compose logs -f core

Les messages du limiteur proviennent des loggers nommés searx.limiter et searx.botdetection et indiquent le réseau client. Un blocage par la blocklist est indiqué par BLOCK 203.0.113.10/32: matched BLOCKLIST, tandis qu’un blocage par l’allowlist est indiqué par PASS 203.0.113.10/32: matched PASSLIST ; dans les deux cas, l’entrée de liste correspondante suit le message. Si le limiteur ne peut pas initialiser son magasin de compteurs, le journal indique The limiter requires Valkey, please consult the documentation. Cela signifie que le limiteur n’a pas été installé.

Chaque vérification individuelle d’un bot est enregistrée au niveau debug. Vous ne la verrez donc pas par défaut. Activez debug pour un test dans settings.yml :

general:
  debug: true

Le journal ajoute alors des lignes de la forme BLOCK 203.0.113.10/32: missing HTTP header Accept-Language. Elles indiquent le réseau client et l’en-tête qui a échoué. Désactivez ensuite debug, car le projet amont déconseille d’exécuter une instance déployée avec debug activé.

Les erreurs du moteur sont très différentes. Elles indiquent un moteur plutôt qu’une adresse IP. Le message détaillé d’expiration du délai est enregistré au niveau debug, tandis que le message engine timeout du thread de recherche est enregistré au niveau error :

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

Une page est également prévue à cet effet. Avec enable_metrics conservé à sa valeur par défaut, true, votre instance enregistre les erreurs des moteurs dans /stats/errors, et /preferences indique quels moteurs répondent actuellement. Une entrée dans /stats/errors identifie une erreur de moteur, mais l’absence de lignes searx.limiter n’exclut pas un blocage par le limiteur, car les vérifications individuelles des bots utilisent searx.botdetection au niveau debug.

Épinglez la version avant tout diagnostic

La configuration du conteneur fournie en amont tient dans deux fichiers.

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

Le fichier Compose récupère docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}. Une variable non définie signifie latest, et latest signifie que l’instance change lors du prochain docker compose pull. Un paramètre qui fonctionnait la semaine dernière peut donc ne plus correspondre au code qui le lit. Les tags SearXNG contiennent une date et un commit. En octobre 2026, le tag indiqué dans le .env.example en amont est 2026.3.25-541c6c3cb. Définissez donc une valeur réelle dans .env :

SEARXNG_VERSION=2026.3.25-541c6c3cb

Consultez les tags publiés et épinglez la release que vous avez réellement testée. Vous pourrez ensuite effectuer le diagnostic sur une cible fixe. Le même fichier .env peut contenir votre clé secrète via SEARXNG_SECRET. Consultez donc le fonctionnement des fichiers d’environnement et des secrets dans Docker Compose avant de valider ce répertoire quelque part.

Le limiteur a besoin de Valkey pour fonctionner

Le limiteur compte les requêtes par client. Ces compteurs doivent être partagés entre les processus workers. Ce stockage est assuré par Valkey, le fork maintenu de Redis. Les anciennes documentations SearXNG appellent ce paramètre redis:. Les versions actuelles lisent valkey:. Reprenez donc le nom de clé dans la documentation actuelle plutôt que dans une ancienne publication. Certaines de ces pages remontent encore plus loin et décrivent Searx au lieu de SearXNG. Il s’agit d’un autre code source, avec un autre limiteur. Vérifiez donc pour lequel des deux projets la page a été rédigée avant d’en copier un bloc de configuration.

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

Le fichier compose fourni en amont démarre déjà un service valkey avec l’image docker.io/valkey/valkey:9-alpine, dans un conteneur nommé searxng-valkey. Ce nom d’hôte est donc résolu sur le réseau compose. La même valeur peut être définie avec la variable d’environnement SEARXNG_VALKEY_URL. Une URL de socket Unix (unix:///path/to/socket.sock?db=0) fonctionne lorsque SearXNG et Valkey partagent le même hôte.

Le comportement en l’absence du stockage dépend d’une autre clé. Avec public_instance: false, le limiteur journalise l’erreur Valkey puis abandonne. L’instance continue donc à répondre sans aucune limitation de débit. Avec public_instance: true, le processus appelle plutôt sys.exit(1), au lieu de servir une instance publique sans protection contre les bots. Un conteneur qui redémarre en boucle après cette erreur d’initialisation de Valkey nécessite de corriger sa connexion à Valkey.

Ce que le limiteur compte réellement

GraphiqueSearXNG limiter: requests allowed per client network, defaults in ip_limit.py
Les données de ce graphique
[
  {
    "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"
  }
]

Lorsque la vérification du link-token est désactivée, un client peut effectuer 15 requêtes pendant une fenêtre de rafale de 20 secondes et 150 pendant une fenêtre de 10 minutes. Lorsqu’elle est activée, un client qui réussit la vérification du link-token contourne les deux compteurs ; un client suspect est limité à 2 par fenêtre de rafale. La dernière ligne est la plus stricte : après 3 requêtes signalées pendant une fenêtre de 30 jours, cette adresse est redirigée vers la page d’accueil au lieu d’effectuer une recherche, et le journal indique BLOCK: too many request from ... in SUSPICIOUS_IP_WINDOW (redirect to /). Réussir la vérification du link-token efface le compteur de requêtes suspectes de ce client.

Ces nombres sont des constantes dans searx/botdetection/ip_limit.py. Ce ne sont pas des paramètres, et limiter.toml ne les expose pas. Pour les modifier, il faut donc modifier le code source. En revanche, /etc/searxng/limiter.toml contrôle les préfixes d’adresses utilisés pour regrouper les clients, la liste des proxies de confiance, la vérification facultative du link-token, ainsi que les listes d’autorisation et de blocage.

Les lignes concernant les clients signalés s’appliquent uniquement lorsque la vérification du link-token est activée, soit via link_token = true dans limiter.toml, soit parce que public_instance: true l’active pour vous. Un client reste alors considéré comme suspect jusqu’à ce qu’il charge une feuille de style dont l’URL contient un token aléatoire. Lorsque le link-token est désactivé, ce qui est le comportement par défaut, tous les clients qui atteignent ces compteurs utilisent les lignes normales.

Les vérifications des en-têtes sont plus strictes, car elles ne signalent rien : une requête qui échoue à l’une d’elles est immédiatement refusée avec le code 429. Chaque vérification est un module dans searx/botdetection/, et la ligne du journal de debug indique l’en-tête qui a échoué :

  • http_accept : l’en-tête Accept ne contient pas text/html.
  • http_accept_encoding : l’en-tête Accept-Encoding ne désigne ni gzip ni deflate.
  • http_accept_language : aucun en-tête Accept-Language n’est présent.
  • http_user_agent : le User-Agent est absent ou correspond à un motif de bot connu.
  • http_sec_fetch : les en-têtes Sec-Fetch-* ne correspondent pas à ceux envoyés par un navigateur. Cette vérification ne s’exécute que pour les requêtes HTTPS provenant de versions de navigateurs connues pour les envoyer. Elle redirige vers la page d’accueil au lieu de répondre avec le code 429. Dans le code source actuel, seul un Sec-Fetch-Mode invalide déclenche réellement cette redirection : un Sec-Fetch-Site ou Sec-Fetch-Dest invalide est enregistré au niveau debug, mais la requête continue.

Un navigateur envoie tous ces éléments. Un appel curl simple n’en envoie presque aucun. Une requête de test écrite manuellement est donc refusée dès le premier essai, alors que la même recherche fonctionne dans un onglet de navigateur. C’est pourquoi le résultat normal est « cela fonctionne dans mon navigateur, mais mon script reçoit une réponse 429 », et non un comportement mystérieux.

Derrière un reverse proxy, le limiter bloque tout le monde en même temps

C’est la manière la plus courante de casser une instance fonctionnelle. SearXNG récupère l’adresse du client depuis la première IP non approuvée dans X-Forwarded-For, puis utilise X-Real-IP, et enfin l’adresse qui a ouvert la connexion. La prise en compte de ces en-têtes est déterminée par trusted_proxies dans limiter.toml. La documentation de la détection des bots indique que trusted_proxies est ignoré lorsque seul X-Real-IP est défini, mais le code dans searx/botdetection/trusted_proxies.py, vérifié le 16 novembre 2026, supprime les deux en-têtes lorsque l’adresse de connexion n’est pas approuvée. Envoyer uniquement X-Real-IP ne permet donc pas de contourner la liste.

Si l’adresse de votre proxy ne figure pas dans cette liste, les en-têtes sont ignorés et chaque visiteur arrive avec l’adresse du proxy. Tous partagent alors le même compteur. Lorsque la vérification des link-token est désactivée, l’ensemble du site est bloqué dès que le total dépasse 150 requêtes en 10 minutes. Lorsque la vérification des link-token est activée, les clients suspects partagent les compteurs plus stricts, tandis qu’un client qui réussit la vérification contourne les compteurs de rafale et de fenêtre longue.

Faire trop confiance est encore plus risqué. Si une plage publique est répertoriée, un visiteur qui se connecte depuis cette plage approuvée peut envoyer son propre en-tête X-Forwarded-For et choisir une nouvelle identité à chaque requête. Répertoriez uniquement l’adresse depuis laquelle votre propre proxy se connecte. Dans Docker, il s’agit généralement d’un bridge network défini dans 172.16.0.0/12, et cette ligne est commentée par défaut.

[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48

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

Le proxy doit également envoyer les en-têtes. Nginx n’ajoute pas automatiquement X-Forwarded-Proto, X-Real-IP ou 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 et Traefik définissent automatiquement les en-têtes forwarded. Avec ces outils, vous devez donc seulement configurer la partie trusted_proxies. Les compromis sont présentés dans choisir un reverse proxy pour un service auto-hébergé. Pour vérifier l’une ou l’autre configuration, activez debug, effectuez une recherche depuis votre téléphone avec les données mobiles, puis vérifiez dans la ligne du journal que le réseau correspond à l’adresse de votre téléphone et non à celle du proxy.

La limite d’API de votre agent dépend de la requête

La sortie JSON est désactivée par défaut. Il faut donc l’ajouter à l’agent :

search:
  formats:
    - html
    - json

Relisez maintenant la ligne correspondante du tableau. Une requête /search avec un paramètre de requête URL format différent de html est comptabilisée dans sa propre fenêtre : 4 requêtes par 1 hour, pour chaque réseau client. L’API accepte les paramètres de formulaire POST, mais un format non HTML fourni uniquement dans les données de formulaire POST n’incrémente pas ce compteur d’API ; les autres contrôles du limiter restent appliqués. Le fait de réussir le contrôle du link-token ne permet pas de contourner le compteur d’API, qui s’exécute en premier. Un agent de recherche qui utilise ?format=json consomme cette limite en une seule tâche, et chaque appel suivant renvoie le code 429. Cette valeur est une constante dans le code source. Vous ne pouvez donc pas l’augmenter dans la configuration. Mais ce n’est pas nécessaire : vous pouvez exclure l’adresse de l’agent du comptage.

La correction propre consiste à indiquer au limiter que ce client est connu. Ajoutez son adresse à la liste d’autorisation dans limiter.toml :

[botdetection.ip_lists]
block_ip = []

pass_ip = [
  '10.8.0.0/24',
]

pass_searxng_org = true

pass_ip est prioritaire sur toutes les autres méthodes. Le commentaire présent dans le code upstream, dans limiter.toml, précise qu’une adresse figurant dans cette liste dispose d’un accès sans restriction. Un client autorisé n’est donc pas soumis à la fenêtre de quatre requêtes, ignore également les contrôles d’en-têtes et peut utiliser un appel curl sans autre paramètre. Limitez la plage autant que possible. Préférez un sous-réseau VPN ou un réseau de conteneurs à toute plage routable. Diriger directement l’agent vers le conteneur sur un réseau interne ne contourne pas le limiter de SearXNG. Ajoutez à la liste d’autorisation l’adresse que SearXNG voit réellement pour le client. La mise en place de cette configuration est décrite dans donner à un agent IA une compétence de recherche SearXNG.

Évitez de diriger un agent vers une instance publique gérée par un tiers. Le trafic automatisé via SearXNG risque de faire bloquer cette instance par les moteurs upstream.

Lorsque les moteurs vous bloquent

GraphiqueHow long SearXNG suspends an engine, search.suspended_times defaults
Les données de ce graphique
[
  {
    "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"
  }
]

Lorsqu’un moteur renvoie sa propre erreur 429 ou une page CAPTCHA, SearXNG lève une exception nommée et cesse de l’interroger pendant un certain temps. Vos visiteurs ne voient jamais cette erreur 429 du moteur de recherche : la recherche renvoie toujours une page de résultats normale, simplement sans ce moteur. Une réponse « trop de requêtes » le suspend pendant 180 secondes, et une réponse « accès refusé » pendant 3 minutes également. Un CAPTCHA ordinaire le suspend pendant 1 hour. Un CAPTCHA fourni par Cloudflare le suspend pendant 15 days, soit la durée par défaut la plus longue de la liste. La ligne CAPTCHA concernée parmi les trois détermine ce qu’il est utile d’essayer ensuite, et les erreurs CAPTCHA ont leur propre ensemble de corrections une fois que vous savez quelle exception votre instance a enregistrée.

Voici les valeurs du searx/settings.yml fourni avec SearXNG, vérifiées le 16 novembre 2026. La documentation des paramètres affiche encore des valeurs plus anciennes et plus longues (une heure pour « trop de requêtes », un jour pour « accès refusé » et pour un CAPTCHA ordinaire). Fiez-vous donc au fichier réellement chargé par votre instance plutôt qu’à une page qui le cite.

Les échecs ordinaires utilisent d’autres paramètres. Un délai d’attente dépassé ou une connexion échouée suspend le moteur pendant search.ban_time_on_fail secondes, soit 5 par défaut, et jamais plus de search.max_ban_time_on_fail, soit 120 par défaut. Une erreur d’analyse est enregistrée dans /stats/errors, mais ne suspend pas du tout le moteur. Un moteur lent récupère donc automatiquement en quelques secondes, tandis qu’un moteur qui a fourni un CAPTCHA est indisponible pendant une heure ou davantage. Cette différence explique un symptôme souvent décrit comme aléatoire : les résultats sont corrects, puis les résultats d’un moteur disparaissent pendant une heure.

Il est préférable de corriger les délais d’attente avant de mettre qui que ce soit en cause. La valeur request_timeout par défaut est de 3.0 secondes. Elle peut être trop courte pour un petit VPS éloigné du serveur edge le plus proche du moteur.

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

request_timeout est la valeur par défaut pour chaque moteur, max_request_timeout est la limite maximale, et un moteur donné peut définir sa propre valeur timeout. Augmenter ces valeurs augmente la latence des pages, mais réduit le nombre d’échecs. Procédez donc par incréments d’une demi-seconde et surveillez /stats/errors au lieu de passer directement à 10.

Si un moteur bloque réellement votre adresse, supprimez-le. Les moteurs suspendus sont ignorés jusqu’à l’expiration de leur suspension. Conserver un moteur qui vous bloque régulièrement ajoute des nouvelles tentatives échouées lorsqu’il redevient éligible.

use_default_settings:
  engines:
    remove:
      - google

Appliquez les modifications avec docker compose restart core, puis lancez quelques recherches et rechargez /stats/errors. Vérifiez que les recherches renvoient des résultats et contrôlez également les erreurs enregistrées.

Une adresse IP de datacentre peut être traitée comme un bot

Google bloque les réseaux qu’il identifie comme générant du trafic automatisé, notamment les réseaux VPN partagés. Aucun réglage de limitation local ne permet de lever ce blocage en amont. Le fait que les moteurs voient votre serveur au lieu de la personne qui saisit la requête est aussi la principale contrepartie en matière de confidentialité liée à l’auto-hébergement. Lisez ce que SearXNG masque réellement avant de supposer qu’il protège davantage de données.

Vous pouvez modifier les moteurs interrogés et décider si votre instance est publiée. SearXNG peut faire passer les requêtes vers les moteurs par un proxy avec outgoing.proxies ou outgoing.using_tor_proxy, ce qui transfère le trafic vers une autre adresse. Une autre adresse de sortie ne garantit pas l’accès : Google bloque également certains services VPN partagés et certains tunnels en raison du trafic automatisé généré par leurs utilisateurs.

Surveillez l’instance pour détecter rapidement les problèmes

SearXNG répond sur son port même lorsque tous les moteurs sont suspendus. Un contrôle de disponibilité qui vérifie uniquement le code d’état reste donc au vert alors que l’instance ne renvoie aucun résultat. Vérifiez plutôt le contenu : lancez une vraie recherche et recherchez dans le corps de la réponse un mot qui doit s’y trouver. Surveillance de mots-clés avec Uptime Kuma fait exactement cela, sans outil supplémentaire. Surveillez également /stats/errors après chaque mise à jour de version, car le HTML des moteurs peut changer et casser un analyseur sans qu’aucune limite de débit n’intervienne.

FAQ

Pourquoi SearXNG renvoie-t-il 429 à chaque visiteur après son placement derrière un reverse proxy ?

Parce que le limiter considère le proxy comme le client. SearXNG ne lit X-Forwarded-For que lorsque l’adresse de connexion figure dans trusted_proxies dans /etc/searxng/limiter.toml. Si elle n’y figure pas, tous les visiteurs partagent le même compteur. Avec la vérification des link-tokens désactivée, ils franchissent ensemble la limite de 150 requêtes en 10 minutes. Avec la vérification des link-tokens activée, les clients suspects partagent des compteurs plus stricts, tandis que les clients qui réussissent la vérification contournent les compteurs de rafale et de fenêtre longue. Ajoutez l’adresse depuis laquelle votre proxy se connecte. Avec Docker, il s’agit généralement de la plage du bridge 172.16.0.0/12. Vérifiez également que le proxy envoie X-Real-IP et X-Forwarded-For. Ne répertoriez jamais une plage que vous ne contrôlez pas, car un client qui se connecte depuis une plage approuvée peut définir cet en-tête et choisir une nouvelle identité à chaque requête.

Combien de requêtes API par heure le limiter de SearXNG autorise-t-il ?

Quatre par réseau client et par heure pour /search requêtes dont le paramètre de requête URL format n’est pas html. Un format autre que HTML fourni uniquement dans les données de formulaire POST n’incrémente pas ce compteur API, mais les autres vérifications du limiter s’appliquent toujours. Cette valeur est définie dans searx/botdetection/ip_limit.py et non dans limiter.toml. Elle ne peut donc pas être augmentée depuis la configuration. Un agent ou un script utilisant ?format=json la transmet en une seule tâche. Une adresse répertoriée dans pass_ip dans limiter.toml bénéficie d’un accès sans restriction et n’est pas comptabilisée. Ajoutez donc l’adresse du client à cet emplacement. Une connexion via un réseau interne ne suffit pas à contourner le limiter de SearXNG.

Pourquoi mes résultats de recherche sont-ils vides sans erreur 429 ?

Les moteurs refusent votre serveur, et non vos utilisateurs. Ouvrez /stats/errors sur votre propre instance. Ce fichier indique chaque moteur qui a échoué et la raison de l’échec. Une entrée CAPTCHA ou access-denied signifie que ce moteur a bloqué l’adresse IP de votre serveur. SearXNG suspend alors le moteur pendant trois minutes après une réponse too-many-requests ou access-denied, pendant une heure après un CAPTCHA classique, et pendant une semaine ou plus après un reCAPTCHA ou un CAPTCHA Cloudflare. Aucun réglage du limiter local ne lève un blocage en amont. Supprimez donc les moteurs qui bloquent votre adresse et conservez ceux qui répondent.

Dois-je activer le limiter sur une instance privée ?

Si personne d’autre que vous n’accède à l’instance, laissez limiter: false. Il ajoute une dépendance à Valkey et bloque vos propres scripts, alors qu’il protège contre un trafic que vous ne recevez pas. Activez-le dès que l’instance obtient une adresse publique, avec public_instance: true. Cette combinaison est volontaire : avec public_instance: true et sans Valkey opérationnel lors de l’initialisation, le processus se termine avec le statut 1 au lieu de fonctionner sans protection.

Cet article vous a-t-il été utile ?