Como corrigir CAPTCHAs dos motores no SearXNG

O que significa um erro de CAPTCHA no SearXNG

Os erros de CAPTCHA do SearXNG são gerados pelos motores que a sua instância consulta. O seu servidor pediu resultados a um motor, mas o motor respondeu com uma página de desafio em vez dos resultados. O SearXNG registou um erro nesse motor porque não havia conteúdo para analisar na resposta. A sua instância está saudável. Uma máquina que não controla decidiu que o seu pedido não parecia ter sido feito por uma pessoa.

Esse facto determina todas as correções abaixo. A decisão foi tomada no próprio hardware do motor, por isso nada na sua settings.yml pode substituí-la. Pode alterar o endereço de origem do pedido, escolher os motores que a instância consulta e definir o comportamento da instância quando um motor começa a recusar pedidos.

Duas falhas que parecem iguais e como distingui-las

A primeira falha ocorre quando a sua própria instância responde HTTP 429 (demasiados pedidos) ao seu próprio browser. Esse é o limitador do SearXNG, a camada de deteção de bots que fica à frente do endpoint de pesquisa. É executado no seu servidor e pode ser configurado por si. o limitador que devolve 429 aos seus próprios utilizadores é um problema separado, com configurações diferentes, e nenhuma das recomendações abaixo se aplica a esse caso.

A segunda falha ocorre a montante. A página de resultados carrega normalmente, mas um ou mais motores não aparecem nos resultados ou apresentam um aviso de erro. Nada na sua instância recusou o pedido. Um motor recusou o seu servidor.

• A página não carrega ou o endpoint de pesquisa responde 429: verifique o seu limitador.
• A página carrega, mas os resultados são escassos, ou um motor aparece assinalado com um erro: verifique o serviço a montante e continue a ler.

As duas falhas podem ocorrer na mesma instância e influenciam-se mutuamente, porque um limitador configurado de forma demasiado permissiva permite a entrada de tráfego que aumenta a taxa de consultas enviadas. Diagnostique cada uma separadamente.

Por que os mecanismos do SearXNG retornam erros de CAPTCHA em um VPS, mas não no meu laptop?

Isso acontece por causa do endereço de origem da solicitação. A sua conexão doméstica usa um endereço de uma faixa de um ISP (provedor de serviços de internet) para consumidores, compartilhada ao longo do tempo por muitas pessoas comuns. O seu VPS usa um endereço de uma faixa de datacenter, e essas faixas são públicas: qualquer pessoa pode consultar quais endereços pertencem a um provedor de hospedagem. Um mecanismo que pretende impedir scrapers começa tratando as solicitações provenientes de faixas de hospedagem como suspeitas, porque muito pouco do tráfego dessas faixas é gerado por uma pessoa usando um navegador.

Outros fatores também se somam ao endereço. A sua instância envia uma solicitação por mecanismo para cada pesquisa do usuário. Assim, mesmo poucos usuários geram, a partir de um único endereço, uma taxa que nenhuma pessoa isolada produz. O SearXNG não mantém uma sessão com o mecanismo nem envia um cookie persistente, por design. Portanto, cada solicitação chega sem histórico associado. O endereço também pode ter um histórico que você não criou, porque os provedores reutilizam endereços e o ocupante anterior pode ter feito scraping a partir dele durante meses.

A recusa nem sempre aparece como uma falha evidente. Um mecanismo pode responder com 403, com 429 ou com HTTP 200 e uma página de desafio no corpo da resposta. Esse último caso confunde, porque uma verificação do código de status indica que o mecanismo está funcionando, enquanto o SearXNG encontra zero resultados na resposta. Por isso, consulte o relatório de erros da sua própria instância em vez de executar curl no mecanismo e verificar apenas a linha de status.

Leia o que a sua instância reporta antes de alterar qualquer coisa

Cada correção abaixo começa pelo nome do mecanismo que está a falhar e pelo motivo que a sua instância registou para esse mecanismo. O SearXNG disponibiliza ambos. A página /stats lista os mecanismos com as respetivas contagens de erros e níveis de fiabilidade. O endpoint /stats/errors devolve os detalhes do erro em JSON, que é mais fácil de guardar e comparar na semana seguinte. Abra-os no navegador que normalmente utiliza para aceder à instância.

O log do contentor regista os mesmos eventos à medida que ocorrem. O nome do serviço apresentado aqui é o utilizado no ficheiro compose publicado com a documentação do contentor. Use o seu se for diferente.

docker compose logs -f core

Execute uma pesquisa que falhe enquanto o log estiver a ser monitorizado. Deverá aparecer uma entrada para o mecanismo que falhou à medida que a pesquisa é executada. Registe o nome do mecanismo e a string exata do motivo apresentada pela sua instância. Não copie o nome de um mecanismo de uma publicação de blog, incluindo esta. O conjunto de mecanismos que bloqueiam endereços de datacenters muda de mês para mês. O mecanismo que falha consigo pode funcionar perfeitamente para o autor do texto que está a ler.

Se a página de resultados não apresentar nenhum erro, mas os resultados forem escassos, consulte display_error_messages para esse mecanismo. O valor predefinido é true. Uma instância que o tenha desativado está a ocultar a única mensagem de que precisa.

Como o SearXNG repete tentativas e suspende um mecanismo que falha

O SearXNG não continua a insistir num mecanismo que recusa os pedidos. Um mecanismo que falha é suspenso. Enquanto está suspenso, é completamente ignorado. É assim que um mecanismo avariado passa a ficar silenciosamente indisponível.

Há duas camadas que controlam este comportamento. Ambas ficam em search:, dentro de settings.yml. Confirme estes nomes de chaves na documentação das definições da versão que realmente executa antes de colar qualquer configuração. Estes nomes mudaram entre releases. Conforme documentado em 2 September 2026, os valores predefinidos são:

search:
  ban_time_on_fail: 5
  max_ban_time_on_fail: 120
  suspended_times:
    SearxEngineAccessDenied: 86400
    SearxEngineCaptcha: 86400
    SearxEngineTooManyRequests: 3600
    cf_SearxEngineCaptcha: 1296000
    cf_SearxEngineAccessDenied: 86400
    recaptcha_SearxEngineCaptcha: 604800

A primeira camada trata falhas normais, como um timeout. A suspensão começa após ban_time_on_fail segundos e aumenta a cada falha consecutiva, até max_ban_time_on_fail. Por predefinição, o limite é de dois minutos. Assim, um mecanismo instável recupera automaticamente poucos minutos depois de o problema desaparecer.

A segunda camada trata as falhas abordadas neste guia. Quando o SearXNG identifica a resposta como um desafio ou uma recusa, em vez de um erro genérico, aplica a entrada correspondente de suspended_times. Esses valores são muito maiores. 86400 segundos correspondem a um dia completo. 604800 correspondem a uma semana. 1296000 correspondem a quinze dias. As chaves com o prefixo cf_ aplicam-se quando o desafio é identificado como sendo do Cloudflare. As chaves com recaptcha_ aplicam-se quando é identificado como reCAPTCHA.

Isto explica o sintoma que mais tempo desperdiça. Encontra a causa, corrige-a e o mecanismo continua sem devolver resultados durante horas. Continua suspenso. A suspensão fica mantida no processo em execução. Por isso, reiniciar o contentor limpa esse estado e a pesquisa seguinte tenta novamente utilizar o mecanismo. Um reinício simples resolve este caso. Antes de começar a recriar imagens sem necessidade, consulte quando um reinício é suficiente e quando é necessário recriar o contentor. Se o mecanismo falhar novamente logo depois do reinício, a correção não resolveu o problema.

Uma definição por mecanismo requer atenção. retry_on_http_error repete um pedido quando o mecanismo responde com os códigos de estado que indicar. Se o mecanismo estiver a bloquear o servidor, as novas tentativas enviam mais tráfego para o sistema que já determinou que o servidor é um bot. Deixe esta definição inalterada, exceto quando estiver a contornar falhas realmente intermitentes de um mecanismo.

A documentação do túnel SSH upstream e o que ele não corrige

Verificado em 2 September 2026, a documentação de administração do SearXNG resolve este problema com um túnel manual. Abra um proxy SOCKS através do seu servidor, configure o navegador do desktop para o utilizar e responda manualmente ao desafio enquanto o motor vê o endereço do servidor.

ssh -q -N -D 8080 user@example.org

-D 8080 abre um servidor SOCKS local na porta 8080 que encaminha as ligações através da sessão SSH. -N não executa nenhum comando remoto e -q mantém a execução silenciosa. Por isso, um túnel funcional não imprime nada nem termina. Verifique-o a partir de um segundo terminal:

curl -x socks://127.0.0.1:8080 http://ipecho.net/plain
curl http://ipecho.net/plain

O primeiro comando deve imprimir o endereço do servidor e o segundo deve imprimir o endereço do desktop. Duas respostas idênticas significam que o pedido não está a passar pelo túnel. Em seguida, configure as definições de rede do navegador para utilizar um proxy SOCKS5 em 127.0.0.1, na porta 8080. Abra no navegador o mesmo verificador de endereços para confirmar que apresenta o endereço do servidor e aceda ao motor que está a apresentar o desafio. Responda ao desafio nesse navegador.

Agora, a limitação real. Quatro fatores limitam este método. O cookie que o motor fornece fica no navegador do desktop. O SearXNG não tem acesso aos cookies do navegador. Por isso, a única informação que pode ajudar a sua instância é o que o motor regista para o próprio endereço. Esse registo expira segundo um prazo definido pelo motor, que não o publica. Nenhuma parte do procedimento é automatizada. Na próxima vez, terá de voltar ao teclado. Numa instância utilizada por outras pessoas, a taxa de consultas que acionou o desafio continua ativa. Por isso, o desafio volta a aparecer.

Use este método para pôr uma instância a funcionar esta tarde. Não crie uma instância dependente dele.

Solução duradoura: remova ou reduza o peso dos mecanismos que bloqueiam as pesquisas

A resposta duradoura mais simples é deixar de consultar um mecanismo que não atende o seu servidor. O seu settings.yml começa com use_default_settings: true na imagem do contentor. Isso significa que uma entrada em engines: com um name correspondente substitui apenas as chaves que indicar e mantém o restante da definição predefinida.

use_default_settings: true

engines:
  - name: <engine name from your stats page>
    disabled: true
  - name: <another engine name>
    weight: 0.3

disabled: true desativa o mecanismo por predefinição, mas mantém-no na página de preferências. Assim, um utilizador que precise dele pode voltar a ativá-lo para as suas próprias pesquisas. inactive: true remove-o completamente das definições do utilizador. É essa a opção adequada para um mecanismo que nunca funcionará a partir do seu endereço. weight tem outra função: ajusta o peso dos resultados desse mecanismo quando o SearXNG os combina e ordena. Um peso inferior a 1 mantém um mecanismo marginal disponível sem permitir que assuma o controlo da primeira página.

Reinicie o contentor depois de editar, faça algumas pesquisas e verifique novamente /stats. Uma página de estatísticas limpa, com seis mecanismos funcionais, é mais útil do que uma página cheia de erros com vinte mecanismos.

Correção duradoura: enviar pedidos de saída através de um proxy

O SearXNG pode enviar os pedidos de saída aos motores através de um proxy, alterando o endereço que o motor vê. Configure-o globalmente em outgoing: ou por motor quando o problema afetar apenas um motor.

outgoing:
  request_timeout: 2.0
  extra_proxy_timeout: 10.0
  proxies:
    all://:
      - socks5h://user:password@proxy:1080

engines:
  - name: <engine name>
    proxies:
      http: socks5h://user:password@proxy:1080
      https: socks5h://user:password@proxy:1080

Prefira socks5h:// a socks5:// quando quiser que o proxy resolva o nome do host, porque h faz com que o nome seja enviado para o proxy em vez de ser resolvido no seu servidor. Aumente também o tempo limite. request_timeout tem o valor predefinido de 2.0 segundos, e um proxy acrescenta uma viagem de ida e volta a cada pedido. Como resultado, motores que antes respondiam a tempo começam a falhar por excederem o tempo limite. extra_proxy_timeout existe precisamente para este caso e acrescenta segundos quando um proxy está em uso.

Custos de um proxy:

• O operador do proxy vê quais os motores consultados pela sua instância e quando. O TLS (segurança da camada de transporte) mantém os termos de pesquisa fora dos respetivos logs, porque a consulta fica dentro do pedido cifrado. No entanto, o padrão e o momento do seu tráfego ficam visíveis para esse operador.
• Um endereço de saída partilhado é usado também por todas as outras pessoas que o pagam. Se essas pessoas fizerem scraping, a reputação do endereço passa a ser também sua, por vezes mais depressa do que o bloqueio que tentava evitar.
• Os pools de proxies residenciais baratos são frequentemente constituídos por dispositivos de consumidores cujos proprietários não aceitaram conscientemente transportar tráfego. Saiba o que está a comprar.
• using_tor_proxy: true encaminha o tráfego através do Tor, mas os endereços dos nós de saída são publicados integralmente. Um motor que bloqueie gamas de datacenters normalmente também bloqueia os nós de saída, ou até com maior rigor.
• A pesquisa passa a depender de um serviço fora do seu servidor. Esse serviço pode falhar segundo o seu próprio calendário e levar os seus resultados consigo.

Um proxy desloca o bloqueio em vez de o remover, e a privacidade da sua instância passa a incluir um terceiro. Se a privacidade limitada é o motivo pelo qual aloja o serviço por conta própria, compare-a com o que uma instância alojada por si realmente oculta e o que não oculta antes de subscrever qualquer serviço.

Corrija de forma duradoura: execute deliberadamente um conjunto menor de motores

A opção que a maioria ignora é aceitar menos motores. O valor do SearXNG está na combinação de resultados, e a combinação de seis motores que respondem sempre é melhor do que vinte, quando metade fica suspensa durante um dia inteiro. Monitorize /stats durante uma semana e mantenha os motores que apresentarem um histórico consistente a partir do seu endereço.

Os motores que usam autenticação com uma chave de API funcionam de forma diferente, porque sabem quem é você e aplicam uma quota, em vez de tentarem determinar se você é uma pessoa. A contrapartida é ter uma conta, manter uma chave no ficheiro de definições e, normalmente, pagar. Para um ou dois motores importantes para si, este é muitas vezes o caminho menos problemático.

Tome esta decisão considerando as outras ferramentas que utiliza. Um motor suspenso fica invisível para qualquer ferramenta que leia resultados através da API, porque a API JSON consultada pelo Open WebUI e por ferramentas semelhantes simplesmente devolve menos resultados, em vez de devolver um erro que a ferramenta consiga detetar. Se algum processo automatizado depender da sua instância, consulte /stats/errors segundo um intervalo definido, em vez de esperar que alguém se queixe de que as respostas pioraram.

Vale a pena insistir?

Responda contando os utilizadores. Uma instância para uma pessoa envia poucas pesquisas por dia a partir de um endereço, uma taxa que muitos motores nunca contestam. Quando um motor apresenta um desafio, a correção é simples: remova-o e quase não notará a sua falta. Esta é a experiência habitual de executar o SearXNG para si próprio num VPS pequeno, e não requer túnel nem proxy.

Uma instância pública ou partilhada é uma máquina diferente que executa o mesmo software. A taxa de consultas é o fator que desencadeia os desafios e aumenta com cada utilizador adicionado, por isso os desafios surgem mais depressa do que qualquer configuração consegue compensar. Planeie desde o início um conjunto menor de motores e lembre-se de que qualquer proxy adicionado passa a transportar as pesquisas de outras pessoas através da sua conta.

Os clientes automatizados ficam entre estes dois casos, mas aproximam-se do mais difícil. Um agente que executa várias pesquisas para responder a uma pergunta gera picos que nenhum utilizador humano produz, por isso uma instância para a qual encaminha agentes de programação e ferramentas de pesquisa encontra desafios mais cedo do que a mesma instância utilizada manualmente. Se esse for o seu caso, escolha o conjunto de motores com base na fiabilidade e não na abrangência, e permita que o agente trabalhe com resultados que consiga realmente obter.

A regra é esta: insista num motor quando ele for a razão para alojar a instância por conta própria e remova-o quando não for.

FAQ

Por que um mecanismo do SearXNG continua sem devolver resultados depois de eu corrigir o problema?

Porque continua suspenso. Quando o SearXNG deteta um desafio ou uma recusa de um mecanismo, deixa de o consultar durante o período definido em search.suspended_times. Esses valores predefinidos variam entre uma hora e quinze dias, consoante o tipo de recusa. A suspensão fica guardada no processo em execução. Por isso, reiniciar o contentor limpa-a e a pesquisa seguinte volta a tentar usar o mecanismo. Se o mecanismo falhar novamente logo depois do reinício, a correção não resolveu o problema.

Um erro de CAPTCHA de um mecanismo é igual ao erro 429 que a minha instância devolve?

O tráfego segue em sentidos opostos. Um erro 429 enviado pela sua instância ao browser significa que o limitador interno do SearXNG considerou o seu pedido automatizado. Esse comportamento pode ser configurado por si. Um CAPTCHA ou erro de bloqueio significa que o mecanismo upstream recusou o seu servidor. Essa decisão é tomada em infraestrutura que não controla. Se a página de resultados carregar e apenas alguns mecanismos não aparecerem, trata-se do segundo caso.

Uma VPN ou um proxy no meu servidor resolve os CAPTCHAs dos mecanismos?

Por vezes, mas há custos. Encaminhar os pedidos de saída através de outgoing.proxies altera o endereço que o mecanismo vê. Isso pode remover um bloqueio associado ao intervalo de endereços do seu datacenter. O operador do proxy passa a ver quais mecanismos consulta e quando. Além disso, um endereço de saída partilhado pode trazer a reputação negativa de outros clientes. A latência adicional também pode causar timeouts, a menos que aumente request_timeout e extra_proxy_timeout. O Tor está disponível através de using_tor_proxy, mas os endereços de saída são públicos e sofrem bloqueios frequentes.

Posso fazer o SearXNG resolver o CAPTCHA automaticamente?

Não existe uma configuração para isso. O método documentado pelo projeto é manual: um túnel SSH SOCKS, o seu próprio browser e a sua intervenção no desafio. Qualquer solução criada para responder automaticamente aos desafios viola a política declarada do mecanismo e deixa de funcionar silenciosamente sempre que o desafio muda. Nesse caso, passa a manter um scraper em vez de executar uma instância de pesquisa. Remover os mecanismos que bloqueiam o seu endereço é a solução que continua a funcionar.