# Erros e status de página: o que falhou e se vale tentar de novo

> Erros da API de pesquisa: os seis códigos HTTP (nunca cobrados), status de página dentro de um 200 e quando tentar de novo. Sem KYC, pague com cripto.

- URL: https://llmwebsearch.com/pt/docs/errors/
- Última atualização: 2026-10-22
- Editor: LLMWebSearch (https://llmwebsearch.com)

Existem dois tipos de problema. Um erro HTTP significa que a chamada inteira falhou e não custa nada. Um status de página significa que a pesquisa funcionou, mas uma página não pôde ser lida; ele aparece dentro de uma resposta 200 normal. Agentes devem tratar os dois de formas diferentes.

**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](https://llmwebsearch.com/pt/docs/response/) 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.

*Python: tentar de novo em 429, 502 e 504 com backoff exponencial*

```python
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](https://llmwebsearch.com/pt/docs/python/) e [Node.js](https://llmwebsearch.com/pt/docs/node/) 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.

---

LLMWebSearch: O LLMWebSearch é uma API de pesquisa na web para agentes de IA que retorna resultados classificados com o conteúdo das principais páginas em Markdown, pago com cripto sem envio de documentos. Os créditos pré-pagos a partir de US$ 1,20/1K pesquisas nunca expiram. Sem KYC — sem documento, sem selfie, sem comprovantes. Pague com cripto.