# Problemas comuns

> URL: https://foura.ai/pt/docs/troubleshooting/common-issues
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Soluções para os problemas mais comuns ao usar a API FourA.

## Conteúdo Vazio ou Incompleto

**Sintoma:** A API retorna status 200, mas o campo `data` está vazio ou sem o conteúdo esperado.

**Causa:** A página de destino usa JavaScript para renderizar o conteúdo após o carregamento inicial da página.

**Solução:** Mude do endpoint single para o endpoint browser. Use `checkText` para verificar se o conteúdo foi carregado:

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Nota: o endpoint do browser retorna o conteúdo no campo `body` (e não em `data`).

## 403 Forbidden ou Páginas de Verificação

**Sintoma:** A API retorna HTML contendo uma página de verificação ou uma página de acesso negado.

**Causa:** O site de destino detectou a request como automatizada e a bloqueou.

**Solução:** Use o endpoint de proxy para rotação automática de IP:

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'
```

Se o problema persistir, aumente `maxTries` para dar mais tentativas à rotação de proxy.

Um 403 retornado pelo alvo chega como HTTP 200 com `status: 403` dentro do body. Um 403 na própria chamada, com um header `X-FourA-Limit`, é diferente: consulte [403 Não incluso no seu plano](#403-not-in-your-plan).

## Erros de tempo limite

**Sintoma:** As requests falham com erro de tempo limite.

**Causa:** A página de destino demora mais para carregar do que o tempo limite configurado.

**Solução:** Aumente `timeout_ms` (o padrão é 15s para single, 30s para browser, 45s para proxy):

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'
```

Para requests de navegador, também verifique se o seu valor de `checkText` realmente aparece na página. Um erro de digitação faz a chamada falhar com `checkText:<your text> not found`.

## 403 Não Incluído no Seu Plano

**Sintoma:** A API retorna 403 com um header `X-FourA-Limit` e um `reason` de `plan_limit_feature` ou `plan_limit_premium`.

```json
{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

**Causa:** Seu plano não inclui o endpoint chamado ou o parâmetro enviado. `plan_limit_feature` cobre um endpoint excluído, e `exitCountries`, `exitState`, `exitCity`, `exitAsn` ou `exitOs` sem direcionamento geográfico. `plan_limit_premium` cobre `exitClass: premium` sem saídas premium, e uma requisição de Proxy que especifica um [local de saída](https://foura.ai/docs/api/endpoints#exit-location) quando seu tráfego premium estiver esgotado. O destino nunca foi contatado e nada foi consumido.

**Solução:** Remova o parâmetro, chame um endpoint incluído no seu plano ou faça um upgrade. A aba **Limits & Features** em [Usage & Limits](https://foura.ai/docs/dashboard/quota) lista o que seu plano inclui. Não repita a requisição sem alterações: nenhum `Retry-After` é definido porque aguardar não altera o resultado.

## 429 Muitas Requisições

**Sintoma:** A API retorna 429.

**Causa:** Uma de duas verificações recusou a chamada, e a resposta indica qual foi. Se contiver um header `X-FourA-Limit`, um dos limites do seu plano foi atingido: requisições simultâneas ou requisições por minuto nesse endpoint, requisições do Browser no dia, ou os créditos ou largura de banda do período de faturamento. Se não houver esse header, o limite compartilhado por minuto da plataforma para esse serviço estava esgotado, o que se refere ao tráfego do FourA e não ao seu.

**Solução:** Leia `X-FourA-Limit` primeiro. Aguarde quando o limite estiver a poucos segundos de distância e pare quando não estiver. Limites do plano liberados por espera informam os segundos no header `Retry-After` e em `retry_after_seconds`; o limite compartilhado os informa em `retryAfter`:

```python
import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)
```

Se o header indicava `plan_limit_concurrency` ou `plan_limit_rate`, a solução é limitar quantas chamadas você mantém abertas e quantas inicia por minuto, em vez de insistir em novas tentativas. Reenviar um lote recusado imediatamente faz com que o lote inteiro seja recusado novamente. Chamadas recusadas não contam para o seu limite por minuto, mas se continuarem chegando a mais que o dobro desse limite, as recusas viram um período de espera: o corpo do erro 429 traz `cooldown: true` e pede para você pausar por 30 segundos (`retry_after_seconds: 30`). [Executar requisições em paralelo](https://foura.ai/docs/how-to/run-requests-in-parallel) mostra o padrão, e **Uso e limites** no [Dashboard](https://foura.ai/dashboard) exibe seus contadores em tempo real ao lado dos seus limites máximos.

## 503 Serviço Indisponível

**Sintoma:** a API retorna status 503.

**Causa:** isso acontece em três casos:

1. **O serviço está na capacidade máxima.** A FourA já está executando tantas requisições nesse motor quantas são permitidas de uma vez, contabilizadas em todo o tráfego e não apenas no seu. `Service at capacity` no campo `error`. Isso geralmente se resolve em segundos.
2. **Serviço temporariamente desativado.** Uma janela de manutenção está em andamento. `Service disabled` no campo `error`.
3. **A FourA não consegue verificar sua chave no momento.** `API key check temporarily unavailable` no campo `error`, com `Retry-After: 5`. Sua chave está normal.

Todos os três casos incluem um campo `retryAfter` na resposta. Nenhum deles é um limite de plano: os limites do seu próprio plano sempre respondem com um header `X-FourA-Limit` em um 403 ou 429, nunca com 503.

**Solução:** aguarde `retryAfter` segundos e tente novamente:

```python
import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")
```

Um erro 503 por capacidade significa que o FourA está ocupado, portanto aplicar backoff e tentar novamente é a solução completa. Se você estiver recebendo uma recusa com 429 e `X-FourA-Limit`, o problema é seu: reduza o número de requests paralelas no seu pipeline.

## 504 Tempo Limite do Upstream Esgotado

**Sintoma:** A API retorna 504 com `{"error": "Upstream timeout"}`.

**Causa:** O processamento não terminou dentro do tempo limite declarado para a request. Um destino lento, uma resolução fria de desafio ou uma página muito grande podem causar isso. Não é um problema com sua chave, seus parâmetros ou seu proxy.

**Solução:** Dê mais tempo à chamada ou tente novamente. O FourA aguarda o seu `timeout_ms` mais uma pequena margem, portanto aumentá-lo estende efetivamente a espera:

```json
{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}
```

Para `/api/auto/` em um alvo protegido, uma primeira chamada a frio pode levar dezenas de segundos. Seu `timeout_ms` cobre toda a sequência e aceita até 180000.

Quando o próprio `/api/auto/` esgota esse limite, a chamada ainda responde HTTP 200. O corpo traz um `error` que começa com `time budget exhausted`, e `status` geralmente é 504 (uma tentativa anterior com falha pode deixar seu próprio status registrado). Aumente `timeout_ms` ou tente novamente.

## 502 Upstream Indisponível

**Sintoma:** A API retorna 502 com `{"error": "Upstream unavailable"}`, ou 503 com `{"error": "Backend service unavailable"}`.

**Causa:** FourA não conseguiu alcançar seu próprio motor (`Upstream unavailable`), ou o motor não forneceu uma resposta utilizável (`Backend service unavailable`), geralmente porque uma instância estava reiniciando. Em `/api/browser/`, uma página espera até 10 segundos por um navegador livre quando todos estão ocupados, e uma página que continuar esperando após isso retorna como este 503.

**Solução:** Tente novamente com um recuo curto. Ambos são classificados como `service_error`, e apenas `success` é cobrado, portanto uma nova tentativa não custa nada a mais. Se persistir por mais de um ou dois minutos, verifique a [página de status](https://updates.foura.ai/status).

## 401 Erros de Autenticação

**Sintoma:** Toda requisição retorna 401 Unauthorized.

**Checklist:**
1. Verifique se o header é `X-API-Key: YOUR_API_KEY` (e não `Authorization: Bearer` ou `Api-Key`)
2. Verifique se há espaços em branco ou quebras de linha extras na sua chave de API
3. Crie uma nova chave a partir do [Dashboard](https://foura.ai/dashboard) se a chave atual puder estar comprometida

## 400 Requisição Inválida

**Sintoma:** Uma chamada a `POST /api/single/`, `/api/proxy/` ou `/api/browser/` retorna 400 com `{"error": "Invalid request: <field>: <reason>; ..."}`.

**Causa:** Um campo no corpo da sua requisição está ausente, possui o tipo incorreto ou está fora do intervalo permitido. A mensagem identifica cada campo que não pôde aceitar e o motivo, até cinco campos, seguido por `and N more` quando houver outros. Nada foi buscado, o resultado é `client_error` e nenhum crédito é consumido.

**Solução:** Corrija os campos indicados e envie a requisição novamente. O mesmo corpo receberá o mesmo erro 400, portanto não tente novamente sem alterações. A [referência do endpoint](https://foura.ai/docs/api/endpoints) lista todos os campos com seus tipos e limites. Em `/api/auto/` o mesmo erro retorna como HTTP 200 com `status: 400` e o motivo em `error`.

## 400 Alvo Resolve para um IP Privado ou Reservado

**Sintoma:** A API retorna 400 com `Refusing to fetch <target>: target resolves to a private or reserved IP range` antes que a requisição saia da FourA.

**Causa:** Seu `url` resolve para uma faixa de IP privada, de loopback ou reservada (RFC 5735, RFC 6598 ou blocos reservados IPv6). FourA recusa esses alvos para que sua rede não possa ser usada para alcançar hosts internos.

**Solução:** Busque uma URL pública. Se você estiver testando, use um alvo público como `https://example.com` ou `https://httpbin.org/get`. Se o alvo pretendido for um serviço que você opera, exponha-o em um hostname público primeiro.

```json
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
```

Um nome de host que não pode ser resolvido não é recusado. A chamada retorna como HTTP 200 com `status: 0` e o motivo (`could not resolve <host>: <reason>`), como qualquer destino que o FourA não consegue alcançar, e não é cobrada.

## 400 Espaço na URL

**Sintoma:** Single, Proxy ou Auto retorna 400 com `invalid URL: it contains a space; encode it as %20 (the URL as sent: "...")` antes que a request saia do FourA.

**Causa:** A URL contém um espaço ou caractere de controle, geralmente um link extraído de uma página exatamente como escrito (`javascript: void(0)`, um link de compartilhamento contendo texto). Nada é buscado, o resultado é `client_error` e nenhum crédito é gasto.

**Solução:** Codifique a URL antes de enviá-la (um espaço é `%20`) e ignore links que não sejam páginas, como os de `javascript:`. O Browser busca essa URL da mesma forma que o Chrome faz.

## 400 O destino é a própria API do FourA

**Sintoma:** A API retorna 400 com `Refusing to fetch <url>: that is the FourA API itself, not a page.` antes que a request saia do FourA.

**Causa:** O seu `url` aponta para `api.foura.ai` ou `eu.api.foura.ai`. Um crawler geralmente faz isso quando resolve um link relativo de uma página em relação à URL da API em vez da URL da própria página, de modo que `/category/news/` se torna `https://eu.api.foura.ai/category/news/`. Nada é buscado e nenhum crédito é gasto.

**Solução:** Resolva cada link em relação à URL da página de origem antes de enviá-lo, por exemplo com `urljoin(page_url, href)` no Python. O endpoint [Inspect](https://foura.ai/docs/api/inspect) (`/inspect`) é o único endereço no host da API que você pode buscar pelo FourA.

## no_eligible_proxy ao usar exitCountries

**Sintoma:** Uma chamada `/api/proxy/` com `exitCountries` retorna HTTP 200 com um envelope de erro JSON:

```json
{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}
```

**Causa:** O pool de proxy atual não possui nenhum exit em funcionamento cujo país visível para o destino corresponda à sua allowlist. O pool padrão nunca faz fallback para um país não solicitado quando você define `exitCountries`. Sem `exitCountries`, a mesma situação responde `{"error": "Failed"}`: o FourA não tinha nenhum exit para tentar, portanto tente novamente após alguns segundos.

Uma request que especifica um local de exit (`exitState`, `exitCity`, `exitAsn`, `exitOs` ou `exitLifetimeMin`, com `exitClass: premium`) sai apenas por exits premium. Quando o FourA não tiver mais nenhum exit premium para tentar para ela, a chamada termina com `"error": "No premium exit answered for this request"` e o mesmo `code: no_eligible_proxy`.

**Solução:** Mantenha o escopo solicitado e tente novamente mais tarde. O pool é atualizado aproximadamente a cada dez minutos, então um país sem correspondência agora frequentemente obtém um dentro de uma hora.

```python
import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")
```

Amplie a lista de países apenas se a exigência de país do seu fluxo de trabalho realmente mudou. Fallbacks silenciosos para outros países podem quebrar a lógica dependente de geolocalização downstream.

## Um Perfil de Navegador É Recusado

**Sintoma:** A chamada retorna com `unknown profile '<id>'`, `no profile matches browser=...` ou `browser profile selection requires unblocker:true`.

**Causa:** O `profile`, `browser`, `os` ou `version` enviado não está no catálogo, ou você enviou um com `unblocker: false`.

**Solução:** Consulte [`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles) para ver o catálogo atual, selecione uma opção dele e mantenha `unblocker` ativado quando escolher um navegador.

## O Corpo da Resposta Retorna como Texto Ilegível

**Sintoma:** O `data` da resposta (ou `body`) contém mojibake ou caracteres ilegíveis quando o destino usa um charset diferente de UTF-8.

**Causa:** Por padrão, o FourA decodifica automaticamente os corpos de resposta para UTF-8 com base no header `Content-Type` do destino ou em uma tag HTML `<meta charset>`. Se o destino fornecer informações incorretas sobre o charset, você receberá texto corrompido.

**Solução:** Para payloads binários (imagens, protobuf, áudio bruto), defina `returnBuffer: true` na request. O Single e o Proxy retornam `data` como um objeto contendo os bytes brutos, `{"type": "Buffer", "data": [<byte values>]}`, sem transcodificação de charset aplicada.

```json
{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}
```

Para alvos de texto que declaram o charset incorretamente, decodifique os bytes brutos você mesmo: faça o fetch com `returnBuffer: true`, leia os valores de bytes em `data.data` e decodifique-os com o charset correto.

## HTML Inesperado em Vez de JSON

**Sintoma:** Você esperava JSON do site de destino, mas recebeu HTML.

**Causa:** A página de destino pode fornecer conteúdo diferente com base nos headers.

**Solução:** Adicione um header `Accept` e ative `unblocker` para headers de navegador realistas:

```bash
curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'
```

Você também pode definir `tryJsonData` como `true` para fazer com que o FourA analise automaticamente respostas JSON.

## O body é uma página de desafio, não o conteúdo

**Sintoma:** A chamada foi bem-sucedida, `status` é 200, mas `data` (ou `body`) é uma verificação de bot em vez da página desejada.

**Causa:** O destino executou uma verificação de bot que o FourA encontrou, mas não conseguiu superar. A resposta indica isso: Single e Proxy retornam `defense` com `solved: false`, e Browser retorna `defenseSolved: false` com o provedor em `defenses.present`.

**Solução:** Verifique `defense.vendor` primeiro e depois escale. Tente um perfil de navegador diferente no Single, mude para o Proxy para obter uma saída diferente ou use o Browser para que o JavaScript seja executado. Referência completa de campos e lista de provedores: [Verificações de site](https://foura.ai/docs/api/site-checks).

Adicione uma substring `validate.data.accept` que apenas a página real contenha. Uma página de verificação que o FourA reconhece nunca é um sucesso: ela retorna com um header `X-FourA-Check-Page` e não é cobrada. Sem `validate`, uma página de verificação não reconhecida pelo FourA, retornada com HTTP 200, conta como sucesso, e você só descobre isso nas etapas seguintes em vez de na própria chamada.

## Ainda com problemas?

Se nenhuma das soluções acima funcionar:

1. Verifique a [página de status](https://updates.foura.ai/status) para incidentes em andamento
2. Analise as métricas de suas requests no [Dashboard](https://foura.ai/dashboard)
3. Entre em contato com o suporte em support@foura.ai com os detalhes da sua request (inclua o `X-FourA-Request-Id` da resposta que falhou)

## Próximos passos

- [Tratamento de erros](https://foura.ai/docs/api/errors): Referência de códigos de erro da API
- [Rate Limits](https://foura.ai/docs/api/rate-limits): Todos os limites de planos e da plataforma, com campos
- [Resultados de requests](https://foura.ai/docs/api/outcomes): Como os resultados classificam o que aconteceu
- [Verificações de site](https://foura.ai/docs/api/site-checks): O que o campo `defense` indica
- [Escolhendo o endpoint correto](https://foura.ai/docs/guides/choosing-task-type): Escolha a melhor abordagem para o seu destino
- [Visão geral do Dashboard](https://foura.ai/docs/dashboard/overview): Monitore suas requests
