# Erros da API

> URL: https://foura.ai/pt/docs/api/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Como tratar erros da API FourA.

## Formato de resposta de erro

A API retorna objetos JSON planos para todos os erros. Não há um objeto `error` aninhado. Quando uma falha possui um código legível por máquina, ele é um campo de nível superior: `reason` em um limite de plano, `code` em uma chamada de proxy sem saída elegível.

```json
{
  "error": "Invalid API key"
}
```

Alguns erros incluem campos extras como `status`, `service`, `retryAfter`, `current` ou `limits` no nível superior:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

## Rastreando uma Request

Toda response da API (sucesso ou erro) inclui um header `X-FourA-Request-Id` com um UUID para essa chamada, exceto quando o corpo não puder ser lido pela FourA (JSON malformado ou corpo acima de 100 KB): isso é recusado antes que um ID seja atribuído. Registre isso do seu lado. Se você precisar perguntar ao suporte o que aconteceu com uma request específica, esse ID nos permite localizá-la.

```bash
curl -i -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://example.com"}'
# HTTP/1.1 200 OK
# X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
# Content-Type: application/json
# ...
```

## Tipos de Erro

### 400: Bad Request

O body da request não contém campos obrigatórios, possui valores inválidos ou indica um destino que a API se recusa a buscar.

Um body que não seja um objeto ou array JSON é considerado JSON malformado e recebe `Invalid JSON in request body`, mostrado abaixo.

No Single, Proxy Finder e Browser, um campo ausente, com tipo incorreto ou fora do intervalo é identificado na mensagem como `<field>: <reason>`. Campos aninhados são unidos por pontos (`validate.status.accept`). Até cinco problemas são listados, separados por `; `, e qualquer item além disso encerra a mensagem como `and <n> more`:

```json
{
  "error": "Invalid request: url: Invalid input: expected string, received undefined"
}
```

É um `client_error` e não é cobrado. O Auto relata um campo que não pode aceitar dentro de um HTTP 200, conforme descrito em Leitura de falhas de `/api/auto/` abaixo.

O mesmo 400 também cobre a proteção contra SSRF. Se o seu `url` resolver para uma faixa de IP privada, de loopback ou de outra forma reservada (RFC 5735, RFC 6598, blocos reservados de IPv6), a request será rejeitada antes de sair da rede da FourA:

```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."
}
```

`<target>` é o endereço, ou o nome do host e o endereço para o qual ele resolveu. Uma URL que não seja analisada, ou que não seja `http://` ou `https://`, recebe o mesmo 400.

Um destino no próprio host de API do FourA (`eu.api.foura.ai` ou `api.foura.ai`) também recebe um 400, no Single, Proxy Finder, Browser e Auto, antes que qualquer item seja buscado ou cobrado. Isso geralmente significa que um link obtido de uma página foi resolvido em relação à URL da API em vez da URL da própria página:

```json
{
  "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL."
}
```

`<url>` é o destino exatamente como você enviou. A página [Inspect](https://foura.ai/docs/api/inspect) é a única exceção: o FourA ainda busca `https://eu.api.foura.ai/inspect` para você.

Uma URL com um espaço ou um caractere de controle dentro dela também recebe um 400, no Single, Proxy Finder e Auto, antes que qualquer coisa seja buscada ou cobrada. Um link copiado de uma página exatamente como escrito geralmente contém um (`javascript: void(0)`, um link de compartilhamento com espaços no texto). Codifique-o, com o espaço como `%20`. O Browser busca essa URL da mesma forma que o Chrome:

```json
{
  "error": "invalid URL: it contains a space; encode it as %20 (the URL as sent: \"https://example.com/a b\")"
}
```

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>`), e não é cobrada. Um destino que o FourA tenta acessar mas não obtém resposta HTTP (o limite de redirecionamentos, um timeout de conexão ou leitura, um reset) também retorna como HTTP 200, com `error` e `total_time` e sem `status`: consulte [Resultados de Requisições](https://foura.ai/docs/api/outcomes#what-a-failed-call-looks-like).

No Single, um response body acima de 128 MB após a decodificação é interrompido nesse ponto. A chamada retorna como HTTP 200 com `"error": "Response body exceeds the 128 MB limit"` e não é cobrada.

JSON malformado no body é recusado da mesma forma, antes que qualquer campo seja lido:

```json
{
  "error": "Invalid JSON in request body"
}
```

Os campos `proxy` e `ignoreProxies` têm seus próprios erros 400. Ambos recebem os IDs opacos de proxy retornados por respostas anteriores, portanto, qualquer outra coisa falha na decodificação:

| Mensagem | O que aconteceu |
|---------|-----------------|
| `Invalid proxy format` | O valor de `proxy` não é um ID de proxy emitido pela FourA. Um endereço de proxy bruto cai aqui. |
| `Invalid ignoreProxies format` | Uma das entradas em `ignoreProxies` não é um ID de proxy. |
| `Proxy not found` | O ID foi decodificado corretamente, mas não aponta mais para uma saída ativa. Escolha uma nova. |
| `Managed exit: this proxy id cannot be pinned to a request` | A saída existe, mas não é uma que a FourA manterá aberta para uma solicitação nomeada. O ID de uma saída premium cai aqui quando seu plano não tem mais tráfego premium disponível. Reutilize a sessão de onde ele veio ou envie a chamada por `POST /api/proxy/` e use a saída escolhida automaticamente. |

**Correção:** Verifique se a sua request inclui todos os campos obrigatórios, se as URLs usam `http://` ou `https://` com qualquer espaço codificado como `%20`, se o host resolve para um endereço público e se qualquer valor de `proxy` é um ID copiado exatamente de uma resposta anterior.

Estes são resultados `client_error`: a request nunca saiu da FourA, portanto nada foi consumido da sua cota.

### 401: Unauthorized

Sua chave de API está ausente ou é inválida.

Chave ausente:

```json
{
  "error": "Missing API key. Include X-API-Key header."
}
```

Chave inválida:

```json
{
  "error": "Invalid API key"
}
```

**Correção:** Verifique se o seu header `X-API-Key` contém uma chave válida. Gere uma nova chave no [Dashboard](https://foura.ai/dashboard) se necessário.

Um 401 sempre significa que a FourA verificou sua chave e a recusou. Quando a FourA não consegue verificar uma chave por alguns segundos, ela responde 503 `API key check temporarily unavailable` em vez disso (veja abaixo), nunca 401.

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

A chamada solicitou um endpoint ou um parâmetro que seu plano não inclui. A response define `X-FourA-Limit` e inclui o mesmo código no body sob `reason`:

```json
{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

`reason` é `plan_limit_feature` para um endpoint excluído pelo plano ou para `exitCountries` e os campos de local de saída em um plano sem geo targeting, e `plan_limit_premium` para `exitClass: premium` em um plano sem saídas premium, ou para um [local de saída](https://foura.ai/docs/api/endpoints#exit-location) sem tráfego premium restante. A string `error` indica o endpoint ou parâmetro.

Um 403 do FourA nunca é sobre o site de destino: o destino nunca foi contatado. Um 403 retornado pelo destino chega como HTTP 200 com `status: 403` dentro do corpo.

**Correção:** Remova o parâmetro, chame um endpoint incluído no seu plano ou faça upgrade. Nenhum `Retry-After` é definido, pois esperar não altera a resposta. Nada foi gasto: o resultado é `rate_limit`, e apenas `success` é faturado.

### 413: Payload muito grande

O corpo JSON da request é maior do que o FourA aceita (100 KB). A resposta não é JSON e não contém `X-FourA-Request-Id`, pois o corpo é recusado antes de ser lido.

**Correção:** Envie um payload `data` menor. Nada foi gasto.

### 429: Limite de taxa excedido

Duas verificações diferentes respondem com 429, e elas não contêm os mesmos campos.

**Limites do seu próprio plano.** A response define um header `X-FourA-Limit` indicando qual limite recusou a chamada e inclui o mesmo código no corpo sob `reason`:

```json
{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}
```

`reason` é um de `plan_limit_concurrency`, `plan_limit_rate`, `plan_limit_browser_daily`, `plan_limit_credits` ou `plan_limit_bandwidth`. Quando uma espera ajuda, o tempo de espera fica em `retry_after_seconds` e no header `Retry-After`, nunca em `retryAfter`. `plan_limit_browser_daily` não inclui nenhum dos dois, pois o limite é renovado à meia-noite UTC e não em segundos. Nada foi gasto: o resultado é `rate_limit`, e apenas `success` é cobrado.

**O limite compartilhado da plataforma.** Sem header `X-FourA-Limit`, e a espera está em `retryAfter`:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`current` e `limits` descrevem o serviço em todo o tráfego, não na sua conta. Uma recusa aqui significa que o FourA está ocupado.

**Correção:** Aguarde o tempo indicado pelo cabeçalho que a resposta trouxer (`Retry-After`, `retry_after_seconds` ou `retryAfter`). Em um rate limit ou de simultaneidade, limite a quantidade de requests abertas em vez de reenviar o lote recusado. Em um limite diário ou de período de faturamento, interrompa a execução. Consulte [Rate Limits](https://foura.ai/docs/api/rate-limits) para ver todos os campos e [Executar Requests em Paralelo](https://foura.ai/docs/how-to/run-requests-in-parallel) para entender o padrão.

### 500: Erro de Servidor

Algo deu errado do nosso lado.

**Correção:** Tente enviar a request novamente após um breve intervalo. Se o erro persistir, verifique a [página de status](https://updates.foura.ai/status) ou entre em contato com o suporte informando o `X-FourA-Request-Id` da resposta com falha.

### 502: Upstream Indisponível

O FourA não conseguiu obter uma resposta do seu próprio mecanismo (`Upstream unavailable`: a conexão falhou) ou recebeu uma resposta ilegível (`Malformed JSON from backend`).

```json
{
  "error": "Upstream unavailable",
  "details": "..."
}
```

**Correção:** Tente novamente com um backoff curto. Isso é do nosso lado, portanto não custa nada para você: o resultado é `service_error` e apenas `success` é faturado.

### 504: Tempo Limite do Servidor Upstream

O mecanismo não terminou dentro do tempo limite reservado para esta request.

```json
{
  "error": "Upstream timeout",
  "details": "the backend did not finish inside the time budget for this request"
}
```

Um 504 está relacionado ao tempo que o trabalho levou, não à sua chave, aos seus parâmetros ou ao seu proxy. Destinos lentos, resoluções de desafios a frio e páginas grandes são as causas mais comuns.

**Correção:** Aumente `timeout_ms` na request (Single aceita até 120000, Browser até 120000, Auto até 180000) ou tente novamente. O FourA aguarda o tempo limite que você declarou mais uma pequena margem, portanto solicitar mais tempo realmente concede mais tempo.

### 503: Serviço Desativado ou com Capacidade Esgotada

Um 503 significa que o serviço está temporariamente indisponível para manutenção ou que o limite de simultaneidade da plataforma foi atingido. Ambas as formas contêm as mesmas chaves: `error`, `status`, `service`, `retryAfter`, `current` e `limits`. Diferencie-as pela string `error`, e não pelos campos presentes.

```json
{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`Service disabled` é manutenção e `current` exibe `0` para ambos os contadores, porque a request foi recusada antes que qualquer coisa fosse medida. `Service at capacity` é o formato de concorrência, e nele `current` contém o uso real da plataforma. Consulte [Rate Limits](https://foura.ai/docs/api/rate-limits) para obter esse formato.

**Correção:** Aguarde `retryAfter` segundos e tente novamente. A página de status lista janelas de manutenção ativas.

Um terceiro formato de 503 não possui `retryAfter`. Isso significa que a engine por trás do seu endpoint não conseguiu receber sua chamada: ela estava reiniciando, falhou no lado do FourA antes da execução da sua request ou (no Browser) todos os navegadores permaneceram ocupados durante os 10 segundos em que uma página aguarda por um. `backend_status` é o status da própria engine e `detail` é o início da resposta dela:

```json
{
  "error": "Backend service unavailable",
  "backend_status": 503,
  "detail": "..."
}
```

É um `service_error` e não é cobrado. Tente novamente após um ou dois segundos. Uma request incorreta por si só nunca chega aqui: ela recebe um 400 informando o campo.

Um quarto 503 significa que o FourA não conseguiu confirmar sua API key temporariamente, por exemplo, durante a alternância do seu banco de dados. A sua key não é o problema e nada foi executado. Ele inclui `Retry-After: 5` e a mesma espera em `retryAfter`:

```json
{
  "error": "API key check temporarily unavailable",
  "status": 503,
  "retryAfter": 5
}
```

Isso não é cobrado. Tente novamente após `retryAfter` segundos. Uma chave confirmada pela FourA nos últimos 10 minutos continua funcionando durante esse momento, portanto essa resposta é rara.

## Como ler falhas de `/api/auto/`

`POST /api/auto/` responde com HTTP 200 sempre que a sequência foi executada, mesmo quando todas as etapas falharam. O resultado real fica no body:

```json
{
  "status": 403,
  "error": "exit blocked by the target defense",
  "attempts": 7,
  "meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}
```

`status` é o último status retornado pelo alvo, ou 502 quando nenhuma tentativa o alcançou (504 quando o tempo limite se esgotou antes). Toda resposta com falha vinda de uma ladder executada também inclui um `attemptReport` que contabiliza os erros encontrados pelas tentativas, com um `summary` de linha única seguro para registro em log, e `meta.attemptsByEngine` e `meta.browserRequests` indicam o que a chamada enviou. Consulte [Por que uma chamada Auto falhou](https://foura.ai/docs/guides/smart-fetch#why-an-auto-call-failed). Um campo de request que o Auto não puder aceitar (um `timeout_ms` abaixo de 5000 ou acima de 180000, por exemplo) retorna da mesma forma: HTTP 200 com `"status": 400` e o motivo em `error`, antes de qualquer tentativa ser feita e sem custo.

Portanto, não faça ramificações com base no status de transporte para o Auto. Em vez disso, leia `status` e `error` no body. Um status não-200 genuíno de `/api/auto/` significa que o FourA rejeitou a chamada antes do início da ladder ou não conseguiu concluí-la: 400 (JSON malformado, um alvo privado ou reservado, ou um alvo no próprio host da API do FourA), 401, 413, 502, 503 ou 504. Um limite de plano é tratado logo na entrada: `exitClass: premium` em um plano sem saídas premium recebe um 403 com `X-FourA-Limit: plan_limit_premium`, antes de qualquer operação ser iniciada. Qualquer outro limite, seu ou da plataforma, retorna dentro do 200 com o respectivo status no body.

Quando um site falha consecutivamente em várias chamadas Auto feitas com a sua chave de API, o Auto responde às próximas chamadas dessa chave para o site imediatamente durante um período, sem tentar a conexão: `"error": "target temporarily unservable, retry later"`, `"status": 503` e um `retryAfter` em segundos. Isso não tem custo; aguarde `retryAfter` segundos.

Um limite de plano atingido por uma das subchamadas também retorna como HTTP 200. O body é a própria recusa, acompanhada de seu `reason`, além de `status` e `meta`, e a resposta inclui o mesmo header `X-FourA-Limit` de uma recusa direta:

```json
{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
```

Quais limites interrompem o ladder e quais apenas fecham um degrau é abordado em [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch#when-your-plans-limits-meet-the-ladder).

## Falhas do Lado do Destino Dentro de 200 OK

Nem toda falha aparece como um status HTTP não 2xx. Quando o destino responde com HTTP 200, mas a resposta do FourA traz um `error` (suas regras de `validate` rejeitaram o corpo, por exemplo) ou o corpo é uma página de verificação que o FourA reconhece, o resultado é `application_error`. Quando o destino retorna um status diferente de 200 que suas regras de `validate` não aceitam, o resultado é `application_fail` e o corpo é entregue sem alterações.

Nenhum dos casos é cobrado: apenas `success` é tarifado. Uma chamada de Browser que encontra todos os navegadores ocupados aguarda até 10 segundos para que um seja liberado. Se nenhum for liberado, ela retorna como o 503 `Backend service unavailable` descrito acima. O Browser também pode responder com HTTP 200 e `"error": "No available browser slot"` quando não conseguiu obter nenhum navegador. Nenhum dos dois é cobrado. Tente novamente após alguns segundos ou mantenha menos chamadas de Browser abertas simultaneamente. A referência de [Resultados](https://foura.ai/docs/api/outcomes) cobre a taxonomia completa.

Uma chamada Single através de um `proxy` fixado por você também pode responder com HTTP 200 e `"error": "The exit gave the same answer for <n> different sites"` junto ao corpo. O FourA detectou que esse exit entregou a mesma página para sites não relacionados, logo a página pertence ao próprio exit, e não àquela solicitada por você. O resultado é `application_error` e não é cobrado. Obtenha um novo exit a partir de `POST /api/proxy/`, que avança e ignora esse tipo de exit por conta própria.

O mesmo se aplica quando a própria rede do exit responde em vez do site. A chamada retorna com `"error": "The exit answered instead of the site (<name>)"` ou `"error": "Corporate web gateway intercepted the request (<name>)"` (uma página de login ou filtragem, ou um redirecionamento para uma), com `"error": "The exit intercepted TLS and answered instead of the site (<name>)"` quando o exit respondeu no lugar do próprio site, ou com `"error": "Honeypot echo proxy (plaintext request dump)"` quando o exit enviou de volta uma cópia da sua própria solicitação. O FourA verifica essas condições independentemente do que suas regras de `validate` definirem, incluindo downloads em `returnBuffer`. Nenhum deles é cobrado. Obtenha um novo exit da mesma forma.

## Codificação de Resposta

O FourA decodifica automaticamente o corpo das respostas para UTF-8. Se o destino fornecer `windows-1251`, `gbk`, `shift_jis`, `iso-8859-*` ou qualquer outro charset declarado no header `Content-Type` ou em uma tag HTML `<meta charset>`, você receberá uma string UTF-8 limpa no campo `data` (single, proxy) ou `body` (browser).

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

## Estratégia de Repetição

Uma política prática de repetição:

```python
import time
import requests

# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def make_request(url, payload, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            url,
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json=payload,
        )
        if resp.status_code == 200:
            return resp.json()

        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        request_id = resp.headers.get("X-FourA-Request-Id", "?")

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")

        # Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
        header = resp.headers.get("Retry-After")
        retry_after = (
            int(header) if header and header.isdigit()
            else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
        )

        if resp.status_code in (429, 503):
            time.sleep(retry_after)
            continue
        if resp.status_code >= 500:   # 500, 502, 503, 504 are all ours to fix
            time.sleep(2 ** attempt)
            continue

        # 400/401/403/404 won't fix themselves
        raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")

    raise RuntimeError(f"Exhausted {max_retries} retries")
```

## Falhas de proxy incluem um relatório

Uma chamada `POST /api/proxy/` que esgota as tentativas retorna como HTTP 200 com um envelope de erro, não como um código de erro HTTP. A string de erro é curta e tem sempre o mesmo formato, portanto um objeto `attemptReport` vem junto com as contagens:

```json
{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
```

Registre `attemptReport.summary` junto ao erro e você saberá se as saídas foram bloqueadas, caíram ou entregaram páginas que suas próprias regras `validate` rejeitaram. Referência de campos e o que fazer sobre cada contagem: [Por que uma Proxy Request esgotou as tentativas](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

## Relacionado

- [Rate Limits](https://foura.ai/docs/api/rate-limits): Limites do plano, simultaneidade e detalhes de RPM
- [Executar Requests em Paralelo](https://foura.ai/docs/how-to/run-requests-in-parallel): Permanecendo dentro da simultaneidade do seu plano
- [Resultados de Requests](https://foura.ai/docs/api/outcomes): Explicação dos sete valores de resultado
- [Problemas Comuns](https://foura.ai/docs/troubleshooting/common-issues): Sintomas, causas, soluções
- [Verificações de site](https://foura.ai/docs/api/site-checks): Quando o corpo é uma página de desafio em vez de um erro
- [Por que uma Proxy Request esgotou as tentativas](https://foura.ai/docs/troubleshooting/proxy-attempt-report): Leitura de `attemptReport`
