Como corrigir limites e erros 429 no SearXNG
Erros 429 no SearXNG podem vir do limitador local ou de pedidos de imagem a montante. Leia o log e verifique os contadores da API para corrigir a causa certa.
Por que o SearXNG retorna erros 429
Uma instância SearXNG auto-hospedada encontra limites de taxa em dois pontos sem relação entre si, e o limite que precisa de corrigir normalmente não é o que se presume. Tanto o limite local como um pedido de imagem a montante podem produzir um 429. O primeiro é local: o próprio limitador do SearXNG concluiu que um pedido veio de um bot e respondeu Too Many Requests com o estado 429. O endpoint /image também encaminha estados de erro a montante, incluindo 429. O segundo é a montante: um motor de pesquisa recusou o endereço IP do servidor. O SearXNG marca esse motor como não responsivo e suspende-o, enquanto os utilizadores continuam a receber uma página de resultados normal, mas com alguns resultados em falta, e não um 429.
Os dois casos não partilham nenhuma correção. O limitador é seu, por isso pode alterá-lo. O bloqueio a montante acontece do lado do motor, por isso alterar o limitador local não o remove. O log indica qual dos casos ocorreu em cerca de um minuto, por isso comece por aí.
Este guia pressupõe a instalação em contentor descrita em uma instância SearXNG auto-hospedada no seu próprio VPS. Todos os nomes de definições abaixo vêm da documentação e do código-fonte atuais do projeto, verificados em 16 November 2026.
Leia o log antes de alterar uma definição
Reproduza o problema com uma janela de log aberta. No ficheiro compose upstream, o serviço SearXNG chama-se core (o respetivo contentor chama-se searxng-core), e os comandos docker compose usam o nome do serviço:
cd ./searxng/
docker compose logs -f coreAs mensagens do limitador são produzidas pelos loggers chamados searx.limiter e searx.botdetection e indicam a rede do cliente. Um bloqueio pela blocklist aparece como BLOCK 203.0.113.10/32: matched BLOCKLIST, e um bloqueio pela allowlist como PASS 203.0.113.10/32: matched PASSLIST, seguido, em cada caso, pela entrada da lista que correspondeu. Se o limitador não conseguir inicializar o armazenamento dos contadores, o log apresenta The limiter requires Valkey, please consult the documentation. Isto significa que o limitador não foi instalado.
Cada verificação individual de bot é registada no nível debug, pelo que não a verá por predefinição. Ative o modo debug para um teste em settings.yml:
general:
debug: trueO log passa então a incluir linhas no formato BLOCK 203.0.113.10/32: missing HTTP header Accept-Language, indicando a rede do cliente e o cabeçalho que falhou. Desative-o novamente depois, porque o upstream indica que não deve executar uma instância em produção com o modo debug ativo.
As falhas dos motores têm um aspeto completamente diferente. Indicam um motor em vez de um endereço IP. A mensagem detalhada de timeout é registada no nível debug, enquanto a mensagem engine timeout da thread de pesquisa é registada no nível error:
HTTP requests timeout (search duration : 3.1 s, timeout: 3.0 s)Também existe uma página para isto. Com enable_metrics no valor predefinido de true, a sua instância regista os erros dos motores em /stats/errors, e /preferences apresenta os motores que estão atualmente a responder. Uma entrada em /stats/errors identifica uma falha de motor, mas a ausência de linhas searx.limiter não exclui um bloqueio pelo limitador, porque as verificações individuais de bot usam searx.botdetection no nível debug.
Fixe a versão antes de depurar qualquer coisa
A configuração do contentor fornecida pelo projeto upstream usa dois ficheiros.
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 .envO ficheiro Compose obtém docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}. Uma variável não definida significa latest, e latest significa que a instância muda sem aviso no próximo docker compose pull. Por isso, uma configuração que funcionou na semana passada pode deixar de corresponder ao código que a lê. As tags do SearXNG incluem uma data e um commit. A tag de exemplo no .env.example upstream em outubro de 2026 é 2026.3.25-541c6c3cb. Defina uma versão real em .env:
SEARXNG_VERSION=2026.3.25-541c6c3cbConsulte as tags publicadas e fixe a release que testou efetivamente. Depois, depure com um alvo fixo. O mesmo ficheiro .env pode armazenar a sua chave secreta através de SEARXNG_SECRET. Leia como funcionam os ficheiros env e os segredos no Docker Compose antes de fazer commit desse diretório em qualquer local.
O limitador precisa do Valkey ou não arranca
O limitador conta os pedidos por cliente, e essas contagens têm de ser partilhadas entre os processos de trabalho. Esse armazenamento é o Valkey, o fork mantido do Redis. Os guias antigos do SearXNG chamam a esta definição redis:. As versões atuais leem valkey:, por isso copie o nome da chave da documentação atual, não de uma publicação antiga. Algumas dessas páginas recuam ainda mais no tempo e descrevem o Searx, não o SearXNG. Trata-se de uma base de código diferente, com um limitador diferente. Por isso, determine para qual dos dois projetos a página foi escrita antes de copiar um bloco de configuração.
use_default_settings: true
server:
secret_key: "change-this-value"
limiter: true
public_instance: false
valkey:
url: valkey://searxng-valkey:6379/0O ficheiro compose upstream já inicia um serviço valkey com a imagem docker.io/valkey/valkey:9-alpine, num contentor chamado searxng-valkey. Por isso, esse nome de host é resolvido dentro da rede compose. O mesmo valor pode ser definido com a variável de ambiente SEARXNG_VALKEY_URL. Um URL de socket Unix (unix:///path/to/socket.sock?db=0) também funciona quando o SearXNG e o Valkey partilham o mesmo host.
O que acontece quando o armazenamento não está disponível depende de outra chave. Com public_instance: false, o limitador regista o erro do Valkey e desiste. Assim, a instância continua a servir pedidos sem qualquer limitação de taxa. Com public_instance: true, o processo chama sys.exit(1) em vez disso, evitando servir uma instância pública sem proteção contra bots. Um contentor que reinicia continuamente depois deste erro de inicialização do Valkey precisa de ter a ligação ao Valkey corrigida.
O que o limitador realmente contabiliza
Os dados por trás deste gráfico
[
{
"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"
}
]Com a verificação de link-token desativada, um cliente pode fazer 15 pedidos numa janela de rajada de 20 segundos e 150 numa janela de 10 minutos. Com a verificação ativada, um cliente que passe essa verificação ignora ambos os contadores; um cliente suspeito pode fazer 2 pedidos por janela de rajada. A última linha é a mais severa: depois de 3 pedidos sinalizados numa janela de 30 dias, esse endereço é redirecionado para a página inicial em vez de fazer a pesquisa, e o log indica BLOCK: too many request from ... in SUSPICIOUS_IP_WINDOW (redirect to /). Passar a verificação de link-token limpa o contador de pedidos suspeitos desse cliente.
Estes números são constantes em searx/botdetection/ip_limit.py. Não são definições de configuração, e limiter.toml não as disponibiliza. Para as alterar, é necessário editar o código-fonte. O que /etc/searxng/limiter.toml controla são os prefixos de endereço usados para agrupar clientes, a lista de proxies confiáveis, a verificação opcional de link-token e as listas de permissão e bloqueio.
As linhas para pedidos sinalizados só se aplicam quando a verificação de link-token está ativada, através de link_token = true em limiter.toml ou porque public_instance: true a ativa automaticamente. A partir desse momento, um cliente é contabilizado como suspeito até carregar uma folha de estilos cujo URL contenha um token aleatório. Com o link-token desativado, que é o comportamento padrão, todos os clientes que chegam a estes contadores usam as linhas normais.
As verificações de cabeçalhos são mais rígidas porque não sinalizam nada: um pedido que falhe uma delas é recusado imediatamente com 429. Cada verificação é um módulo em searx/botdetection/, e a linha do log de depuração indica o cabeçalho que falhou:
http_accept: o cabeçalhoAcceptnão contémtext/html.http_accept_encoding: o cabeçalhoAccept-Encodingnão indicagzipnemdeflate.http_accept_language: não existe um cabeçalhoAccept-Language.http_user_agent:User-Agentestá em falta ou corresponde a um padrão de bot conhecido.http_sec_fetch: os cabeçalhosSec-Fetch-*não correspondem aos enviados por um browser. Esta verificação só é executada em pedidos HTTPS provenientes de versões de browser conhecidas por os enviar e redireciona para a página inicial em vez de responder com 429. No código-fonte atual, apenas umSec-Fetch-Modeinválido desencadeia efetivamente esse redirecionamento: umSec-Fetch-SiteouSec-Fetch-Destinválido é registado no nível de depuração, mas o pedido continua.
Um browser envia todos estes cabeçalhos. Uma chamada simples de curl envia quase nenhum, por isso um pedido de teste escrito manualmente é recusado logo na primeira tentativa, enquanto a mesma pesquisa funciona num separador do browser. Por isso, "funciona no meu browser, mas o meu script recebe 429" é o resultado normal, não um mistério.
Atrás de um reverse proxy, o limiter bloqueia todos ao mesmo tempo
Esta é a forma mais comum de interromper uma instância que estava a funcionar. O SearXNG obtém o endereço do cliente a partir do primeiro IP não confiável em X-Forwarded-For, recorre a X-Real-IP e, por fim, usa o endereço que abriu a ligação. A decisão de confiar ou não nesses cabeçalhos é controlada por trusted_proxies em limiter.toml. A documentação de deteção de bots afirma que trusted_proxies é ignorado quando apenas X-Real-IP está definido, mas o código em searx/botdetection/trusted_proxies.py, verificado em 16 November 2026, elimina ambos os cabeçalhos quando o endereço de ligação não é confiável. Por isso, enviar apenas X-Real-IP não contorna a lista.
Se o endereço do seu proxy não estiver nessa lista, os cabeçalhos são ignorados e todos os visitantes chegam com o endereço do proxy. Assim, partilham um único contador. Com a verificação de link-token desativada, todo o site é bloqueado quando o total ultrapassa 150 pedidos em 10 minutos. Com a verificação de link-token ativada, os clientes suspeitos partilham os contadores mais restritivos, enquanto um cliente que passa na verificação ignora os contadores de rajada e de janela longa.
Confiar em excesso é pior. Se for listado um intervalo público, um visitante que se ligue a partir desse intervalo confiável pode enviar o seu próprio cabeçalho X-Forwarded-For e escolher uma nova identidade em cada pedido. Liste apenas o endereço a partir do qual o seu próprio proxy estabelece ligações. No Docker, esse endereço costuma estar numa rede bridge dentro de 172.16.0.0/12, e essa linha vem comentada.
[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48
trusted_proxies = [
'127.0.0.0/8',
'::1',
'172.16.0.0/12',
]O proxy também tem de enviar os cabeçalhos. O Nginx não adiciona X-Forwarded-Proto, X-Real-IP ou X-Forwarded-For por si só:
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;
}O Caddy e o Traefik definem os cabeçalhos encaminhados automaticamente. Com eles, só precisa de executar a parte trusted_proxies da configuração. As vantagens e limitações são descritas em escolher um reverse proxy para um serviço self-hosted. Para verificar qualquer uma das configurações, ative debug, faça uma pesquisa a partir do telemóvel usando dados móveis e confirme se a rede na linha do log é o endereço do telemóvel, e não o do proxy.
O limite da API do agente depende do pedido
A saída JSON está desativada por predefinição, por isso é necessário adicioná-la ao agente:
search:
formats:
- html
- jsonAgora leia novamente a linha do gráfico. Um pedido /search com um parâmetro de consulta URL format diferente de html é contado na sua própria janela: 4 pedidos por 1 hour, por rede cliente. A API aceita parâmetros de formulário POST, mas um formato não HTML fornecido apenas nos dados do formulário POST não incrementa este contador da API; as outras verificações do limitador continuam a aplicar-se. Passar na verificação do token de ligação não ignora o contador da API, que é executado primeiro. Um agente de pesquisa que use ?format=json esgota esse limite numa tarefa, e todas as chamadas seguintes devolvem 429. O número é uma constante no código-fonte, por isso não pode aumentá-lo na configuração, mas não precisa de o fazer: pode retirar o endereço do agente da contagem.
A correção adequada é indicar ao limitador que este cliente não é desconhecido. Adicione o endereço à lista de permissões em limiter.toml:
[botdetection.ip_lists]
block_ip = []
pass_ip = [
'10.8.0.0/24',
]
pass_searxng_org = truepass_ip tem prioridade sobre todos os outros métodos, e o comentário do próprio upstream em limiter.toml diz que um endereço nessa lista tem acesso sem restrições. Assim, um cliente na lista de permissões não fica sujeito à janela de quatro pedidos, também ignora as verificações dos cabeçalhos e uma chamada curl simples funciona. Mantenha o intervalo tão pequeno quanto possível e prefira uma sub-rede VPN ou uma rede de contentores a qualquer rede encaminhável. Apontar o agente diretamente para o contentor numa rede interna não ignora o limitador do próprio SearXNG; coloque na lista de permissões o endereço do cliente que o SearXNG efetivamente vê. A configuração disso é descrita em dar a um agente de IA uma competência de pesquisa no SearXNG.
A opção a evitar é apontar um agente para uma instância pública mantida por outra pessoa. O tráfego automatizado através do SearXNG pode fazer com que essa instância seja bloqueada pelos motores upstream.
Em vez de serem os motores a bloquear
Os dados por trás deste gráfico
[
{
"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"
}
]Quando um motor responde com o seu próprio erro 429 ou com uma página CAPTCHA, o SearXNG gera uma exceção identificada e deixa de consultar esse motor durante algum tempo. Os visitantes nunca veem esse erro 429 do motor de pesquisa: a pesquisa continua a devolver uma página normal de resultados, apenas sem esse motor. Uma resposta de excesso de pedidos suspende-o durante 180 segundos, e uma resposta de acesso negado durante 3 minutes também. Um CAPTCHA simples suspende-o durante 1 hour. Um CAPTCHA servido através do Cloudflare suspende-o durante 15 days, o período predefinido mais longo da lista. A linha de CAPTCHA em que a instância ficou determina o que vale a pena tentar a seguir, e os erros de CAPTCHA têm o seu próprio conjunto de correções quando souber qual foi a exceção registada pela instância.
Estes são os valores do searx/settings.yml distribuído com o SearXNG, verificados em 16 November 2026. A documentação das definições ainda apresenta valores mais antigos e mais longos (uma hora para excesso de pedidos, um dia para acesso negado e para um CAPTCHA simples). Por isso, confie no ficheiro que a instância realmente carrega, e não numa página que o cita.
As falhas comuns usam definições diferentes. Um timeout ou uma ligação falhada suspende o motor durante search.ban_time_on_fail segundos, 5 por predefinição, e nunca durante mais de search.max_ban_time_on_fail, 120 por predefinição. Um erro de análise é registado em /stats/errors, mas não suspende o motor. Assim, um motor lento recupera por si próprio em poucos segundos, enquanto um motor que serviu um CAPTCHA fica indisponível durante uma hora ou mais. Esta diferença explica um sintoma que é frequentemente descrito como aleatório: os resultados estão normais e, depois, os resultados de um motor desaparecem durante uma hora de cada vez.
Vale a pena corrigir os timeouts antes de atribuir a culpa a alguém. O request_timeout predefinido é de 3.0 segundos, o que ainda pode ser insuficiente para um VPS pequeno que esteja longe do servidor edge mais próximo de um motor.
outgoing:
request_timeout: 3.5
max_request_timeout: 10.0
engines:
- name: bing
timeout: 5.0request_timeout é o valor predefinido para todos os motores, max_request_timeout é o limite máximo e um único motor pode ter o seu próprio timeout. Aumentar estes valores troca latência da página por menos falhas. Por isso, aumente-os em intervalos de meio segundo e monitorize /stats/errors, em vez de passar diretamente para 10.
Se um motor estiver efetivamente a bloquear o seu endereço, remova-o. Os motores suspensos são ignorados até a suspensão expirar. Manter um motor que bloqueia repetidamente o seu endereço acrescenta novas tentativas falhadas quando voltar a estar elegível.
use_default_settings:
engines:
remove:
- googleAplique as alterações com docker compose restart core, execute algumas pesquisas e recarregue /stats/errors. Confirme que as pesquisas devolvem resultados e verifique também os erros registados.
Um IP de um datacenter pode ser tratado como um bot
A Google bloqueia redes que identifica como origem de tráfego automatizado, incluindo redes VPN partilhadas. Nenhuma definição de limitação local remove esse bloqueio a montante. O facto de os motores de pesquisa verem o seu servidor em vez da pessoa que introduz a consulta também faz parte do compromisso de privacidade assumido ao alojar o serviço por conta própria. Vale a pena ler quanto o SearXNG realmente oculta antes de assumir que ele protege mais informações.
Pode alterar os motores de pesquisa consultados e decidir se a sua instância fica listada publicamente. O SearXNG pode encaminhar os pedidos aos motores através de um proxy com outgoing.proxies ou outgoing.using_tor_proxy, transferindo o tráfego para um endereço diferente. Um endereço de saída diferente não garante o acesso: a Google também bloqueia alguns serviços VPN partilhados e túneis devido ao tráfego automatizado gerado pelos respetivos utilizadores.
Monitore a instância para detetar problemas primeiro
O SearXNG responde na sua porta mesmo quando todos os motores estão suspensos. Por isso, uma verificação de disponibilidade que monitoriza apenas o código de estado permanece verde enquanto a instância não devolve resultados. Verifique o conteúdo. Faça uma pesquisa real e procure no corpo da resposta uma palavra que espera encontrar. monitorização por palavra-chave do Uptime Kuma faz exatamente isso sem ferramentas adicionais. Monitorize também /stats/errors depois de cada atualização de versão, porque os motores alteram o respetivo HTML e um analisador pode deixar de funcionar sem qualquer relação com limites de taxa.
FAQ
Por que o SearXNG devolve 429 a todos os visitantes depois de o colocar atrás de um reverse proxy?
Porque o limitador está a contabilizar o proxy como cliente. O SearXNG só lê X-Forwarded-For quando o endereço de ligação está listado em trusted_proxies em /etc/searxng/limiter.toml. Se não estiver listado, todos os visitantes partilham o mesmo contador. Com a verificação de tokens de ligação desativada, todos ultrapassam em conjunto o limite de 150 pedidos por 10 minutos. Com a verificação de tokens de ligação ativada, os clientes suspeitos partilham contadores mais restritivos, enquanto os clientes que passam a verificação ignoram os contadores de rajada e de janela longa. Adicione o endereço a partir do qual o proxy estabelece a ligação. Em Docker, normalmente é o intervalo da bridge 172.16.0.0/12. Certifique-se também de que o proxy envia X-Real-IP e X-Forwarded-For. Nunca liste um intervalo que não controle, porque um cliente que se ligue a partir de um intervalo confiável pode definir esse cabeçalho e escolher uma nova identidade em cada pedido.
Quantos pedidos à API por hora o limitador do SearXNG permite?
Quatro por rede de cliente por hora para /search pedidos cujo parâmetro de consulta URL format não seja html. Um formato que não seja HTML, fornecido exclusivamente nos dados do formulário POST, não incrementa esse contador da API, embora as outras verificações do limitador continuem a aplicar-se. Esse número é definido em searx/botdetection/ip_limit.py, e não em limiter.toml, pelo que não pode ser aumentado a partir da configuração. Um agente ou script que use ?format=json transmite-o numa única tarefa. Um endereço listado em pass_ip em limiter.toml obtém acesso sem restrições e não é contabilizado, por isso adicione aí o endereço do cliente. Estabelecer a ligação através de uma rede interna, por si só, não ignora o limitador do SearXNG.
Por que os meus resultados de pesquisa aparecem vazios sem um erro 429?
Os engines estão a recusar o seu servidor, não os seus utilizadores. Abra /stats/errors na sua própria instância. Esse ficheiro identifica cada engine que falhou e explica o motivo. Uma entrada de CAPTCHA ou de acesso negado significa que esse engine bloqueou o endereço IP do seu servidor. O SearXNG suspende então o engine durante três minutos depois de uma resposta de demasiados pedidos ou de acesso negado, durante uma hora depois de um CAPTCHA simples e durante uma semana ou mais depois de um reCAPTCHA ou CAPTCHA do Cloudflare. Nenhuma definição do limitador local remove um bloqueio a montante. Remova os engines que bloqueiam o seu endereço e mantenha os que respondem.
Devo ativar o limitador numa instância privada?
Se ninguém além de si acede à instância, deixe limiter: false. Essa opção adiciona uma dependência de Valkey e bloqueia os seus próprios scripts. Também protege contra tráfego que não existe no seu caso. Ative-a assim que a instância tiver um endereço público, juntamente com public_instance: true. Essa combinação é deliberada: com public_instance: true e sem um Valkey funcional durante a inicialização, o processo termina com o estado 1 em vez de ficar a funcionar sem proteção.