Respuesta rápida
¿Qué errores puede devolver la API de LLMWebSearch y se cobran?
LLMWebSearch tiene seis errores HTTP: 400 invalid_parameter, 401 invalid_api_key, 402 insufficient_credits, 429 rate_limited, 502 search_failed y 504 search_timeout. Ninguno se cobra. Las páginas que no se pueden leer muestran un content_status dentro de un 200. Una búsqueda que funciona cuesta 1 crédito, desde 1,20 US$/1K búsquedas a fecha de octubre de 2026. Sin KYC; paga con criptomonedas.
¿Qué errores HTTP existen?
El body siempre es {"error": {"code": "…", "message": "…"}}. Ningún error consume un crédito.
| HTTP | code | Causa | ¿Reintentar? |
|---|---|---|---|
| 400 | invalid_parameter | Falta un parámetro obligatorio o un valor está fuera de rango | No: corrige la solicitud |
| 401 | invalid_api_key | La clave falta, es incorrecta o fue revocada | No: revisa la clave |
| 402 | insufficient_credits | El saldo no puede pagar esta llamada | No: compra un pack |
| 429 | rate_limited | Más llamadas por minuto de las que permite la cuenta | Sí, tras una pausa |
| 502 | search_failed | La búsqueda no se pudo completar | Sí, con backoff |
| 504 | search_timeout | Sin resultados de búsqueda en 30 segundos | Sí, con backoff |
¿En qué se diferencia el estado de una página de un error?
El estado de una página describe un resultado, no la llamada. La búsqueda se ejecutó, los resultados están ahí y credits_used está establecido como de costumbre. Solo falta el contenido de esa página, y content_status indica por qué: blocked_by_robots, blocked_by_site_policy, target_refused, fetch_failed, fetch_timeout u unsupported_content.
No los trates como fallos para reintentar toda la búsqueda. Usa los demás resultados, el snippet de la página que falta o una fuente distinta. La página del formato de respuesta explica cada estado en una tabla.
¿Por qué nunca reintentáis ante una negativa?
Porque una negativa es la respuesta del sitio y la respetamos. Nuestro lector respeta robots.txt: se identifica como LLMWebSearch, sigue las reglas que un sitio escribe para él o para todos los robots, y deja fuera el contenido de cualquier página que no tenga permitido leer. Un sitio que establece Content-Signal: ai-input=no en su robots.txt mantiene las páginas de su sitio fuera del contenido de tus resultados. Cuando un sitio rechaza nuestro lector con un 403, un 429 o una página de challenge, lo informamos como target_refused con el estado del sitio en target_status.
Cuando un sitio rechaza a nuestro lector, el resultado vuelve sin contenido y con el estado del sitio: nunca resolvemos CAPTCHAs, iniciamos sesión en cuentas ni sorteamos un bloqueo o un paywall. Tampoco reintentamos con otra identidad ni con un navegador camuflado. Tu agente no debería entrar en bucle en una página así: el resultado no va a cambiar y el sitio ha dicho que no.
¿Cuándo debe reintentar mi código?
Solo en 429, 502 y 504. Espera y vuelve a intentarlo, duplicando la espera cada vez y añadiendo un poco de aleatoriedad para que los workers en paralelo no reintenten a la vez. Con tres a cinco intentos es suficiente; después, informa del fallo.
Nunca reintentes 400, 401 ni 402: la misma petición da la misma respuesta hasta que cambies algo. En el caso de páginas, fetch_failed y fetch_timeout pueden funcionar más tarde, mediante una nueva búsqueda o una llamada a /extract. target_refused, blocked_by_robots y blocked_by_site_policy son definitivos.
import os
import random
import time
import requests
API = "https://llmwebsearch.com/api/v1/search"
HEADERS = {"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}
RETRY_ON = {429, 502, 504}
def search(body, attempts=5):
delay = 1.0
for attempt in range(1, attempts + 1):
resp = requests.post(API, headers=HEADERS, json=body, timeout=60)
if resp.status_code == 200:
return resp.json()
err = resp.json().get("error", {})
if resp.status_code not in RETRY_ON or attempt == attempts:
raise RuntimeError(f"{resp.status_code} {err.get('code')}: {err.get('message')}")
time.sleep(delay + random.uniform(0, delay / 2))
delay = min(delay * 2, 30)
data = search({"q": "how to rotate api keys without downtime"})
unread = [r["url"] for r in data["results"] if r["content_status"] not in ("ok", "not_requested")]
print("credits:", data["credits_used"], "| pages not read:", unread)
¿Qué hago ante un 402 insufficient_credits?
Detente y recarga. La llamada no se ejecutó y no costó nada. Para no parar a mitad de un trabajo largo, consulta antes tu saldo con GET https://llmwebsearch.com/api/v1/credits, que es gratis, y compáralo con el número de búsquedas que tienes previstas. Recuerda que una búsqueda con read superior a 3 necesita 2 créditos.
Los créditos salen de los packs comprados con tu saldo en criptomonedas. Los créditos de búsqueda no caducan: lo que no uses este mes seguirá ahí el año que viene.
¿Cómo me mantengo dentro del rate limit?
Limita cuántas llamadas se ejecutan a la vez en tu propio código. Cada cuenta tiene un límite de llamadas por minuto, que se muestra en el panel; pídelo a soporte y se puede aumentar. Un grupo pequeño de workers en paralelo, de cuatro a ocho para la mayoría de los agentes, mantiene un ritmo constante sin picos. Las páginas de Python y Node.js muestran cada una un grupo así.
Cuando recibas un 429, haz una pausa antes del siguiente intento en lugar de lanzarlo de inmediato. Reintentar de inmediato solo añade más llamadas rechazadas.
Errores: preguntas frecuentes
¿Una búsqueda con todas las páginas rechazadas sigue costando un crédito?
Sí, si la búsqueda en sí funcionó: sigues recibiendo los resultados clasificados y los snippets. El precio de una búsqueda no depende de cuántas de sus páginas se hayan podido leer.
¿Un 401 puede deberse a una clave revocada?
Es posible. Una clave revocada, una errata, un prefijo Bearer que falta o un header que nunca nos llegó dan todos 401 invalid_api_key. Crea una clave API por agente, app o compañero de equipo y revoca cualquiera de ellas desde el panel sin tocar las demás.
¿Por qué una página devolvió fetch_timeout?
Las páginas se leen en paralelo, y una página que tarda más de 15 segundos se devuelve sin contenido para que no bloquee toda la respuesta. Los sitios lentos a veces responden en un intento posterior.
¿Puedo ver mis llamadas fallidas?
Sí. El historial del panel lista tus llamadas durante 30 días, incluidas las fallidas, con su estado y sus créditos. Las llamadas fallidas muestran 0 créditos.