SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor

Cómo corregir los errores 429 de SearXNG

Los errores 429 de SearXNG los causa su limitador local. Si un motor bloquea la IP, faltan resultados sin 429. Lea el registro y corrija el límite correcto.

Por qué SearXNG devuelve errores 429

Una instancia de SearXNG autohospedada alcanza límites de tasa en dos lugares no relacionados, y el límite que debe corregir normalmente no es el que supone. Sólo uno de ellos produce un 429. El primero es local: el limitador propio de SearXNG determina que una solicitud procede de un bot y responde Too Many Requests con el estado 429. Esa es la única parte de SearXNG que envía un 429 al cliente. El segundo es ascendente: un motor de búsqueda rechaza la dirección IP de su servidor. SearXNG marca ese motor como no receptivo y lo suspende, y los usuarios siguen recibiendo una página de resultados normal con elementos ausentes, no un 429.

Los dos casos no comparten ninguna solución. El limitador es suyo, por lo que puede cambiarlo. El bloqueo ascendente ocurre en el lado de Google, por lo que nada en su settings.yml lo eliminará. El registro indica cuál de los dos casos tiene en aproximadamente un minuto, así que empiece por ahí.

Esta guía presupone la instalación mediante contenedor descrita en una instancia de SearXNG autohospedada en su propio VPS. Todos los nombres de configuración que aparecen a continuación proceden de la documentación y el código fuente ascendentes actuales, comprobados el 23 de octubre de 2026.

Lee el registro antes de cambiar una configuración

Reproduzca el problema con una ventana del registro abierta. En el archivo compose de upstream, el servicio SearXNG se llama core (su contenedor se llama searxng-core), y los comandos docker compose usan el nombre del servicio:

cd ./searxng/
docker compose logs -f core

Los mensajes del limitador proceden del logger llamado searx.limiter y muestran la red del cliente. Una coincidencia con la blocklist aparece como BLOCK 203.0.113.10/32: matched BLOCKLIST, y una coincidencia con la allowlist como PASS 203.0.113.10/32: matched PASSLIST; después de cada una figura la entrada de la lista que coincidió. Si el limitador no puede acceder a su almacén de contadores, el registro muestra The limiter requires Valkey, please consult the documentation, lo que significa que no se está contabilizando nada.

Cada comprobación individual de bot se registra en el nivel debug, por lo que no la verá de forma predeterminada. Active debug para una prueba en settings.yml:

general:
  debug: true

El registro añade entonces líneas con el formato BLOCK 203.0.113.10/32: missing HTTP header Accept-Language, que indican la red del cliente y la cabecera que falló. Desactívelo después, porque upstream indica que no debe ejecutar una instancia desplegada con debug activado.

Los fallos de los motores no se parecen en nada a eso. Muestran el nombre de un motor en lugar de una IP, los registros actuales también los escriben en el nivel debug y el caso más común es un timeout, seguido del nombre de la excepción:

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

También hay una página para esto. Con enable_metrics en su valor predeterminado de true, su instancia registra los errores de los motores en /stats/errors, y /preferences muestra qué motores están respondiendo actualmente. Si /stats/errors está lleno y el registro no contiene líneas searx.limiter, el limitador no es el problema.

Fije la versión antes de depurar cualquier problema

La configuración del contenedor de upstream consta de dos archivos.

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

El archivo de Compose obtiene docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}. Una variable sin definir significa latest, y latest significa que la instancia cambia en el siguiente docker compose pull. Por tanto, una configuración que funcionó la semana pasada puede dejar de coincidir con el código que la lee. Las etiquetas de SearXNG incluyen una fecha y un commit. La etiqueta de ejemplo de upstream .env.example a fecha de octubre de 2026 es 2026.3.25-541c6c3cb, así que establezca una versión concreta en .env:

SEARXNG_VERSION=2026.3.25-541c6c3cb

Compruebe las etiquetas publicadas y fije la versión que haya probado realmente. Después, depure siempre con un objetivo fijo. El mismo archivo .env contiene la clave secreta. Consulte cómo funcionan los archivos de entorno y los secretos en Docker Compose antes de confirmar ese directorio en cualquier repositorio.

El limitador necesita Valkey o no se ejecuta

El limitador cuenta las solicitudes de cada cliente, y esos contadores deben compartirse entre los procesos de trabajo. Ese almacén es Valkey, la bifurcación mantenida de Redis. Las guías antiguas de SearXNG llaman a este ajuste redis:. Las versiones actuales leen valkey:, así que copie el nombre de la clave de la documentación actual y no de una publicación antigua. Algunas de esas páginas se remontan aún más atrás y describen Searx en lugar de SearXNG, que es una base de código diferente con un limitador diferente. Por eso, determine para cuál de los dos proyectos se escribió la página antes de copiar un bloque de configuración.

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

El archivo compose del proyecto ya ejecuta un servicio valkey basado en la imagen docker.io/valkey/valkey:9-alpine, en un contenedor llamado searxng-valkey, por lo que ese nombre de host se resuelve dentro de la red de compose. También puede establecer el mismo valor con la variable de entorno SEARXNG_VALKEY_URL. Una URL de socket Unix (unix:///path/to/socket.sock?db=0) funciona cuando SearXNG y Valkey comparten el mismo host.

Lo que ocurre cuando falta el almacén depende de otra clave. Con public_instance: false, el limitador registra el error de Valkey y se detiene, por lo que la instancia sigue atendiendo solicitudes sin ningún límite de tasa. Con public_instance: true, el proceso llama a sys.exit(1) en su lugar, porque una instancia pública con la protección contra bots averiada recopila CAPTCHA (prueba de Turing pública y completamente automatizada para diferenciar ordenadores de personas) de cada motor en un día. Si un contenedor entra en un ciclo de reinicios justo después de establecer public_instance: true, esta es la causa. La última línea antes de cada salida identifica a Valkey.

Qué cuenta realmente el limitador

GráficoSearXNG limiter: requests allowed per client IP, defaults in ip_limit.py
Los datos de este gráfico
[
  {
    "label": "Burst, normal client",
    "max_requests": 15,
    "window": "20 seconds"
  },
  {
    "label": "Burst, flagged client",
    "max_requests": 2,
    "window": "20 seconds"
  },
  {
    "label": "Sustained, normal client",
    "max_requests": 150,
    "window": "10 minutes"
  },
  {
    "label": "Sustained, flagged client",
    "max_requests": 10,
    "window": "10 minutes"
  },
  {
    "label": "Any non-HTML format",
    "max_requests": 4,
    "window": "1 hour"
  },
  {
    "label": "Flagged requests before block",
    "max_requests": 3,
    "window": "30 days"
  }
]

Un cliente normal puede realizar 15 solicitudes dentro de una ventana de ráfaga de 20 segundos y 150 dentro de una ventana de 10 minutos. Cuando un cliente se marca como sospechoso, el límite baja a 2 por ventana de ráfaga. La última fila es la más estricta: después de 3 solicitudes marcadas dentro de una ventana de 30 días, esa dirección se redirige a la página de inicio en lugar de realizar la búsqueda, y el registro muestra BLOCK: too many request from ... in SUSPICIOUS_IP_WINDOW (redirect to /).

Estos números son constantes en searx/botdetection/ip_limit.py. No son opciones de configuración y limiter.toml no los expone, por lo que cambiarlos requiere editar el código fuente. Lo que sí controla /etc/searxng/limiter.toml son los prefijos de dirección usados para agrupar clientes, la lista de proxies de confianza, la comprobación opcional del token de enlace y las listas de permitidos y bloqueados.

Las filas para clientes marcados sólo se aplican cuando la comprobación del token de enlace está activada, ya sea mediante link_token = true en limiter.toml o porque public_instance: true la activa automáticamente. En ese caso, un cliente se considera sospechoso hasta que su navegador carga una hoja de estilos cuya URL contiene un token aleatorio, algo que un script nunca hace. Con el token de enlace desactivado, que es el valor predeterminado, todos los clientes usan las filas normales.

Las comprobaciones de cabeceras son más estrictas porque no marcan nada: una solicitud que no supera una de ellas se rechaza inmediatamente con 429. Cada comprobación es un módulo de searx/botdetection/, y la línea del registro de depuración indica la cabecera que falló:

  • http_accept: la cabecera Accept no contiene text/html.
  • http_accept_encoding: la cabecera Accept-Encoding no identifica ni gzip ni deflate.
  • http_accept_language: no existe ninguna cabecera Accept-Language.
  • http_user_agent: falta User-Agent o coincide con un patrón de bot conocido.
  • http_sec_fetch: las cabeceras Sec-Fetch-* no coinciden con las que envía un navegador. Esta comprobación sólo se ejecuta en solicitudes HTTPS procedentes de versiones de navegador que se sabe que las envían, y redirige a la página de inicio en lugar de responder con 429. En el código fuente actual, sólo un Sec-Fetch-Mode no válido activa realmente esa redirección: un Sec-Fetch-Site o Sec-Fetch-Dest no válido se registra en el nivel de depuración, pero la solicitud continúa.

Un navegador envía todas estas cabeceras. Una llamada normal de curl envía casi ninguna, por lo que una solicitud de prueba escrita manualmente se rechaza en el primer intento, mientras que la misma búsqueda funciona en una pestaña del navegador. Por eso «funciona en mi navegador, pero mi script recibe 429» es el resultado normal y no un misterio.

Detrás de un reverse proxy, el limitador bloquea a todos a la vez

Esta es la forma más habitual de romper una instancia que funcionaba. SearXNG obtiene la dirección del cliente a partir de la primera IP no confiable de X-Forwarded-For, usa X-Real-IP como alternativa y, si tampoco está disponible, toma la dirección que abrió la conexión. trusted_proxies en limiter.toml determina si se confía en esas cabeceras. La documentación de detección de bots indica que trusted_proxies se ignora cuando sólo se define X-Real-IP, pero el código de searx/botdetection/trusted_proxies.py, comprobado el 23 de octubre de 2026, descarta ambas cabeceras cuando la dirección que se conecta no es confiable. Por tanto, enviar sólo X-Real-IP no permite evitar la lista.

Si la dirección de su proxy no está en esa lista, las cabeceras se ignoran y todos los visitantes llegan con la dirección del proxy. En consecuencia, comparten un único contador y todo el sitio queda bloqueado cuando el total supera 150 solicitudes en 10 minutos. Un usuario que recargue varias veces una página de resultados puede dejar sin servicio a todos los demás.

Confiar demasiado es peor. Si se incluye un rango público, cualquier visitante puede enviar su propia cabecera X-Forwarded-For y elegir una identidad nueva en cada solicitud. Esto desactiva el limitador para cualquiera que sepa cómo aprovecharlo. Incluya sólo la dirección desde la que se conecta su propio proxy. En Docker suele ser una red bridge dentro de 172.16.0.0/12, y esa línea aparece comentada.

[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48

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

El proxy también debe enviar las cabeceras. Nginx no añade ninguna por sí solo:

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 y Traefik configuran las cabeceras reenviadas automáticamente. Con ellos sólo debe configurar la parte trusted_proxies. Las ventajas y desventajas se explican en cómo elegir un reverse proxy para un servicio autohospedado. Para verificar cualquiera de las dos configuraciones, active debug, haga una búsqueda desde el teléfono usando datos móviles y confirme que la red de la línea del registro corresponde a la dirección del teléfono, no a la del proxy.

Tu agente recibe cuatro solicitudes de API por hora

La salida JSON está deshabilitada de forma predeterminada, por lo que debes añadirla al agente:

search:
  formats:
    - html
    - json

Ahora vuelve a leer la fila de la tabla. Cada solicitud que pide un formato distinto de HTML se contabiliza en su propia ventana: 4 solicitudes por 1 hour, por dirección. Un agente de investigación agota ese límite en una sola tarea, y cada llamada posterior devuelve 429. El número es una constante en el código fuente, por lo que no puedes aumentarlo desde la configuración. Sin embargo, no es necesario hacerlo: puedes excluir por completo la dirección del agente del recuento.

La solución correcta es indicar al limitador que este cliente no es desconocido. Añade su dirección a la lista de permitidos en limiter.toml:

[botdetection.ip_lists]
block_ip = []

pass_ip = [
  '10.8.0.0/24',
]

pass_searxng_org = true

pass_ip tiene prioridad sobre cualquier otro método, y el comentario del propio upstream en limiter.toml indica que una dirección incluida en esa lista tiene acceso sin restricciones. Por tanto, un cliente incluido en la lista de permitidos no está sujeto a la ventana de cuatro solicitudes y también omite las comprobaciones de cabeceras. Además, una llamada curl sin parámetros funciona. Mantén el rango lo más reducido posible y prefiere una subred VPN o una red de contenedores antes que cualquier red enrutable. La otra solución correcta es mantener al agente completamente fuera de la ruta pública: configúralo para usar la dirección del contenedor en la red interna, donde el proxy y su limitador nunca ven el tráfico. La configuración correspondiente se explica en cómo proporcionar a un agente de IA una capacidad de búsqueda de SearXNG.

Debes evitar apuntar un agente a una instancia pública administrada por otra persona. Es la forma más rápida de conseguir que los motores upstream bloqueen la dirección IP de un voluntario, y por eso el formato JSON está deshabilitado de forma predeterminada.

Cuando los motores le bloquean

GráficoHow long SearXNG suspends an engine, search.suspended_times defaults
Los datos de este 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"
  }
]

Cuando un motor responde con su propio 429 o con una página CAPTCHA, SearXNG genera una excepción con nombre y deja de consultarlo durante un tiempo. Sus visitantes nunca ven ese 429: la búsqueda sigue mostrando una página de resultados normal, pero sin ese motor. Una respuesta de demasiadas solicitudes lo suspende durante 180 segundos, y una respuesta de acceso denegado durante 3 minutes también. Un CAPTCHA normal lo suspende durante 1 hour. Un CAPTCHA servido mediante Cloudflare lo suspende durante 15 days, el valor predeterminado más largo de la lista, porque esa respuesta indica que el bloqueo está en el perímetro y reintentar no ayudará. La fila de CAPTCHA en la que haya terminado determina qué conviene probar después, y los errores de CAPTCHA tienen su propio conjunto de soluciones cuando sepa qué excepción registró su instancia.

Estos son los valores del searx/settings.yml incluido con SearXNG, comprobados el 23 de octubre de 2026. La documentación de configuración todavía muestra valores anteriores y más largos (una hora para demasiadas solicitudes, un día para acceso denegado y para un CAPTCHA normal), así que confíe en el archivo que carga realmente su instancia y no en una página que cite esos valores.

Los fallos normales usan otros ajustes. Un tiempo de espera agotado o una conexión fallida suspenden el motor durante search.ban_time_on_fail segundos, 5 de forma predeterminada, y nunca durante más de search.max_ban_time_on_fail, 120 de forma predeterminada. Un error de análisis se registra en /stats/errors, pero no suspende el motor. Por tanto, un motor lento se recupera por sí solo en unos segundos, mientras que un motor que sirvió un CAPTCHA desaparece durante una hora o más. Esta diferencia explica un síntoma que suele parecer aleatorio: los resultados son correctos y, de repente, desaparecen los resultados de un motor durante una hora.

Conviene corregir los tiempos de espera antes de atribuir el problema a otra causa. El valor predeterminado de request_timeout es 3.0 segundos, que puede ser insuficiente para un VPS pequeño situado lejos del servidor perimetral más cercano del motor.

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

request_timeout es el valor predeterminado para todos los motores, max_request_timeout es el límite máximo y un motor concreto puede tener su propio timeout. Aumentar estos valores intercambia latencia de página por menos fallos, así que hágalo en incrementos de medio segundo y supervise /stats/errors en lugar de saltar directamente a 10.

Si un motor está bloqueando realmente su dirección, elimínelo. Cada búsqueda espera al motor más lento, así que conservar uno suspendido permanentemente añade latencia y no devuelve resultados.

use_default_settings:
  engines:
    remove:
      - google

Aplique los cambios con docker compose restart core, ejecute varias búsquedas y vuelva a cargar /stats/errors. Si la página sigue vacía después de cinco minutos de uso real, el cambio ha funcionado.

Una IP de centro de datos será tratada como un bot

La dirección de su VPS pertenece a un rango de alojamiento, y los grandes motores de búsqueda califican esos rangos como automatización. Algunos de ellos sirven un CAPTCHA a cada petición proveniente de dicha dirección, sin importar cuán educadas sean las cabeceras o cuán lento sea el ritmo. Ninguna configuración en settings.yml cambia ese juicio. Que los motores vean su servidor en lugar de la persona que escribe la consulta es, además, la totalidad del intercambio de privacidad que usted realizó al autoalojar el servicio, y vale la pena leer cuánto oculta realmente SearXNG antes de asumir que cubre más.

Lo que usted puede cambiar es a qué motores consulta y si su instancia aparece listada públicamente. Una instancia privada utilizada por un solo hogar rara vez activa bloqueos. Una instancia pública en una IP de alojamiento acumulará suspensiones en los motores más estrictos, y ese es el estado normal del software, no un fallo en su configuración. SearXNG puede enrutar las peticiones a los motores a través de un proxy con outgoing.proxies o outgoing.using_tor_proxy, lo cual traslada el tráfico a una dirección diferente. Los nodos de salida y los grupos de proxies económicos tienen peor reputación que los rangos de alojamiento, así que espere que ese movimiento empeore los resultados.

Supervise la instancia para detectar los fallos primero

SearXNG responde en su puerto incluso cuando todos los motores están suspendidos. Por eso, una comprobación de disponibilidad que sólo supervise el código de estado permanece en verde aunque la instancia no devuelva resultados. Compruebe el contenido. Solicite una búsqueda real y busque una palabra que espera encontrar en el cuerpo de la respuesta. Supervisión de palabras clave con Uptime Kuma hace exactamente eso sin herramientas adicionales. Supervise también /stats/errors después de cada actualización de versión, porque los motores cambian su HTML y un analizador puede dejar de funcionar sin que intervenga ningún límite de tasa.

FAQ

¿Por qué SearXNG devuelve 429 a todos los visitantes después de colocarlo detrás de un reverse proxy?

Porque el limitador cuenta al proxy como cliente. SearXNG sólo lee X-Forwarded-For cuando la dirección desde la que se conecta está incluida en trusted_proxies dentro de /etc/searxng/limiter.toml. Si no está incluida, todos los visitantes comparten un único contador y superan juntos el límite de 150 solicitudes por 10 minutos. Añada la dirección desde la que se conecta el proxy. En Docker, normalmente es el rango de bridge 172.16.0.0/12. Asegúrese también de que el proxy envíe X-Real-IP y X-Forwarded-For. Nunca incluya un rango que no controle, porque una red de confianza permite que cualquier visitante establezca esa cabecera y elija una identidad nueva en cada solicitud.

¿Cuántas solicitudes de API por hora permite el limitador de SearXNG?

Cuatro por dirección IP y por hora. Cualquier solicitud que pida un formato distinto de HTML se contabiliza en una ventana independiente de una hora. Ese número se define en searx/botdetection/ip_limit.py, no en limiter.toml, por lo que no se puede aumentar desde la configuración. Un agente o un script consume ese límite en una sola tarea. Una dirección incluida en pass_ip dentro de limiter.toml obtiene acceso sin restricciones y no se contabiliza. Añada allí la dirección del cliente o acceda a la instancia mediante una red interna donde el limitador nunca vea la solicitud.

¿Por qué los resultados de búsqueda aparecen vacíos sin ningún error 429?

Los motores están rechazando al servidor, no a los usuarios. Abra /stats/errors en su propia instancia. Ese archivo indica qué motores fallaron y por qué. Una entrada de CAPTCHA o de acceso denegado significa que el motor bloqueó la dirección IP del servidor. SearXNG suspende entonces el motor: durante tres minutos después de una respuesta de demasiadas solicitudes o de acceso denegado, durante una hora después de un CAPTCHA normal y durante una semana o más después de un CAPTCHA de Google o Cloudflare. Ningún ajuste local puede levantar un bloqueo del servicio ascendente. Elimine los motores que bloquean su dirección y conserve los que responden.

¿Debo habilitar el limitador en una instancia privada?

Si nadie excepto usted accede a la instancia, deje limiter: false. Añade una dependencia de Valkey y bloquea sus propios scripts. Además, protege contra un tráfico que no tiene. Habilítelo en cuanto la instancia tenga una dirección pública, junto con public_instance: true. Esa combinación es intencionada: con public_instance: true y sin un Valkey operativo, el proceso termina con el estado 1 en lugar de ejecutarse sin protección.

¿Te resultó útil este artículo?