Resposta rápida
Quais erros a API do LLMWebSearch pode retornar e eles são cobrados?
LLMWebSearch tem seis erros HTTP: 400 invalid_parameter, 401 invalid_api_key, 402 insufficient_credits, 429 rate_limited, 502 search_failed e 504 search_timeout. Nenhum é cobrado. Páginas que não podem ser lidas mostram um content_status dentro de um 200. Uma pesquisa que funciona custa 1 crédito, a partir de US$ 1,20/1K pesquisas em outubro de 2026. Sem KYC; pague com cripto.
Quais erros HTTP existem?
O body é sempre {"error": {"code": "…", "message": "…"}}. Nenhum erro usa um crédito.
| HTTP | code | Causa | Tentar de novo? |
|---|---|---|---|
| 400 | invalid_parameter | Um parâmetro obrigatório está faltando ou um valor está fora do intervalo | Não: corrija a requisição |
| 401 | invalid_api_key | A chave está faltando, errada ou foi revogada | Não: verifique a chave |
| 402 | insufficient_credits | O saldo não cobre esta chamada | Não: compre um pacote |
| 429 | rate_limited | Mais chamadas por minuto do que a conta permite | Sim, após uma pausa |
| 502 | search_failed | A pesquisa não pôde ser concluída | Sim, com backoff |
| 504 | search_timeout | Nenhum resultado de pesquisa em 30 segundos | Sim, com backoff |
Como o status de uma página é diferente de um erro?
Um status de página descreve um resultado, não a chamada. A pesquisa foi executada, os resultados estão lá e credits_used está definido como de costume. Só falta o conteúdo daquela página específica, e content_status diz o motivo: blocked_by_robots, blocked_by_site_policy, target_refused, fetch_failed, fetch_timeout ou unsupported_content.
Não trate isso como falhas para repetir a pesquisa inteira. Use os outros resultados, o snippet da página ausente ou outra fonte. A página formato da resposta explica cada status em uma tabela.
Por que vocês nunca tentam de novo em caso de recusa?
Porque uma recusa é a resposta do site, e nós a respeitamos. Nosso leitor respeita o robots.txt: ele se identifica como LLMWebSearch, segue as regras que um site escreve para ele ou para todos os robôs e deixa de fora o conteúdo de qualquer página que não tem permissão para ler. Um site que define Content-Signal: ai-input=no no seu robots.txt mantém as suas páginas fora do conteúdo dos seus resultados. Quando um site rejeita nosso leitor com 403, 429 ou uma página de desafio, informamos isso como target_refused com o status do site em target_status.
Quando um site recusa o nosso leitor, o resultado volta sem conteúdo e com o status do site: nunca resolvemos CAPTCHAs, não entramos em contas nem contornamos um bloqueio ou um paywall. Também não tentamos de novo com outra identidade ou um navegador disfarçado. Seu agente não deve ficar em loop nessa página: o resultado não vai mudar, e o site disse não.
Quando meu código deve tentar de novo?
Somente em 429, 502 e 504. Espere, depois tente de novo, dobrando a espera a cada vez e adicionando um pouco de aleatoriedade para que workers paralelos não tentem de novo em sincronia. De três a cinco tentativas bastam; depois disso, reporte a falha.
Nunca tente de novo em 400, 401 ou 402: a mesma requisição dá a mesma resposta até você mudar algo. Para páginas, fetch_failed e fetch_timeout podem funcionar mais tarde, por meio de uma nova pesquisa ou de uma chamada /extract. target_refused, blocked_by_robots e blocked_by_site_policy são 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)
O que devo fazer em caso de 402 insufficient_credits?
Pare e recarregue. A chamada não foi executada e não custou nada. Para evitar parar no meio de um job longo, verifique seu saldo primeiro com GET https://llmwebsearch.com/api/v1/credits, que é gratuito, e compare com o número de pesquisas que você planeja. Lembre que uma pesquisa com read acima de 3 precisa de 2 créditos.
Os créditos vêm de packs comprados com seu saldo em cripto. Os créditos de pesquisa não têm data de expiração: o que você não usar este mês continua lá no ano que vem.
Como fico abaixo do rate limit?
Limite quantas chamadas rodam ao mesmo tempo no seu próprio código. Toda conta tem um limite de chamadas por minuto, exibido no dashboard; peça ao suporte e ele pode ser aumentado. Um pequeno pool de workers paralelos, de quatro a oito para a maioria dos agentes, mantém um ritmo constante sem picos. As páginas Python e Node.js mostram esse pool.
Quando você receber um 429, faça uma pausa antes da próxima tentativa em vez de disparar na hora. Tentar de novo imediatamente só adiciona mais chamadas recusadas.
Erros: perguntas frequentes
Uma pesquisa com todas as páginas recusadas ainda custa um crédito?
Sim, se a pesquisa em si funcionou: você ainda recebe os resultados ranqueados e os snippets. O preço de uma pesquisa não depende de quantas de suas páginas puderam ser lidas.
Um 401 é causado por uma chave revogada?
Pode ser. Uma chave revogada, um erro de digitação, um prefixo Bearer faltando ou um header que nunca chegou até nós todos dão 401 invalid_api_key. Crie uma chave de API por agente, app ou colega de equipe e revogue qualquer uma delas no dashboard sem afetar as outras.
Por que uma página retornou fetch_timeout?
As páginas são lidas em paralelo, e uma página que leva mais de 15 segundos é retornada sem conteúdo para não travar a resposta inteira. Sites lentos às vezes respondem em uma tentativa posterior.
Consigo ver minhas chamadas com falha?
Sim. O histórico do dashboard lista suas chamadas por 30 dias, incluindo as que falharam, com status e créditos. Chamadas com falha mostram 0 créditos.