Docs › Solução de problemas › Problemas Comuns

Problemas Comuns

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

Conteúdo vazio ou incompleto

Sintoma: A API retorna o 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 único para o endpoint de navegador. Use checkText para verificar se o conteúdo foi carregado:

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 de browser retorna o conteúdo no campo body (não em data).

Páginas 403 Forbidden ou CAPTCHA

Sintoma: A API retorna HTML contendo um desafio de CAPTCHA ou uma página de acesso negado.

Causa: O site de destino detectou o request como automatizado e o bloqueou.

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

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 à rotação de proxy mais tentativas.

Erros de timeout

Sintoma: As requests falham com um erro de timeout.

Causa: A página de destino leva mais tempo para carregar do que o timeout configurado.

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

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 valor de checkText realmente aparece na página. Um erro de digitação sempre causará um timeout.

429 Too Many Requests (Limite de RPM)

Sintoma: A API retorna o status 429 com uma mensagem "rate limit exceeded".

Causa: Você excedeu seu limite de requests por minuto (RPM). Isso é diferente dos limites de simultaneidade (veja o 503 abaixo).

Solução: Use o campo retryAfter da response para aguardar o tempo correto antes de tentar novamente:

import time
import requests

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:
            body = resp.json()
            wait = body.get("retryAfter", 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"}
)

Verifique seu uso atual no Dashboard para ver seus rate limits.

503 Service Unavailable

Sintoma: a API retorna o status 503.

Causa: isso acontece em dois casos:

  1. Limite de simultaneidade atingido. Você tem muitos requests simultâneos em execução. Isso é diferente do 429, que limita requests por minuto. Com o 503, você não excedeu seu RPM, mas atingiu o número máximo de requests que podem ser executados ao mesmo tempo.
  2. Serviço temporariamente desativado. Uma janela de manutenção está em andamento.

Ambos os casos incluem um campo retryAfter na response.

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

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):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

Se você está atingindo os limites de concorrência 503 regularmente, reduza o número de requests paralelos no seu pipeline de scraping ou verifique o limite de concorrência do seu plano no Dashboard.

504 Upstream Timeout

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

Causa: O trabalho não foi concluído dentro do orçamento de tempo que você declarou para o request. Um alvo lento, uma resolução inicial de desafio ou uma página muito grande causarão isso. Não é um problema com a sua chave, os seus parâmetros ou o seu proxy.

Solução: Dê mais tempo para a chamada ou tente novamente. O FourA espera pelo seu timeout_ms mais uma pequena margem, então aumentá-lo realmente estende a espera:

{
  "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 cadeia e aceita até 180000.

502 Upstream Indisponível

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

Causa: A FourA alcançou seu próprio mecanismo, mas não pôde usar a resposta, geralmente porque uma instância estava reiniciando.

Solução: Tente novamente com um backoff curto. Ambos são classificados como service_error, e apenas success é faturado, então uma nova tentativa não custa nada a mais para você. Se durar mais do que um ou dois minutos, verifique a página de status.

401 Erros de Autenticação

Sintoma: Toda request retorna 401 Unauthorized.

Checklist:

  1. Verifique se o header é X-API-Key: YOUR_API_KEY (não Authorization: Bearer ou Api-Key)
  2. Verifique se há espaços em branco extras ou quebras de linha em sua chave de API
  3. Crie uma nova chave a partir do Dashboard se a atual puder estar comprometida

400 O Alvo Resolve para um IP Privado/Reservado

Sintoma: A API retorna 400 com Target <ip> resolves to a private/reserved IP antes que a request saia da FourA.

Causa: Sua url resolve para um intervalo de IP privado, loopback ou reservado (RFC 5735, RFC 6598 ou blocos reservados IPv6). A 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ê executa, exponha-o em um hostname público primeiro.

{ "error": "Target <ip> resolves to a private/reserved IP" }

no_eligible_proxy ao usar exitCountries

Sintoma: Uma chamada /api/proxy/ com exitCountries retorna HTTP 200 com um envelope de erro 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 proxies atual não tem uma saída funcional cujo país visível ao alvo corresponda à sua lista de permissões. O FourA nunca faz fallback para um país não solicitado quando você define exitCountries.

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

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")

Apenas amplie a lista de países se o requisito de país do seu fluxo de trabalho realmente mudou. Recursos de fallback silenciosos para outros países podem quebrar a lógica dependente de geolocalização no downstream.

O Response Body Retorna como Texto Ilegível

Sintoma: O response data (ou body) contém mojibake ou caracteres ilegíveis quando o alvo usa um charset diferente de UTF-8.

Causa: Por padrão, o FourA decodifica automaticamente os response bodies para UTF-8 com base no header Content-Type do alvo ou em uma tag HTML <meta charset>. Se o alvo mentir sobre seu charset, você obterá um texto ilegível.

Solução: Para payloads binários (imagens, protobuf, áudio bruto), defina returnBuffer: true no request. O corpo retorna como um buffer base64 sem nenhuma transcodificação de charset aplicada.

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

Para alvos de texto que declaram incorretamente seu charset, decodifique os bytes brutos você mesmo: busque com returnBuffer: true, decodifique em base64 e, em seguida, aplique o charset correto.

HTML inesperado em vez de JSON

Sintoma: Você esperava JSON do site alvo, mas recebeu HTML.

Causa: A página alvo pode servir conteúdo diferente com base nos headers.

Solução: Adicione um header Accept e habilite unblocker para obter headers de navegador realistas:

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 que o FourA analise automaticamente as respostas JSON.

O Corpo é uma Página de Desafio, Nã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 que você queria.

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

Solução: Verifique defense.vendor primeiro, depois avance. Tente um perfil de navegador diferente no Single, mude para o Proxy para uma saída diferente, ou use o Browser para que o JavaScript seja executado. Referência completa dos campos e lista de fornecedores: Defesas Anti-Bot.

Adicione uma substring validate.data.accept que apenas a página real contém. Sem ela, uma página de desafio retornada com HTTP 200 conta como sucesso, e você descobre isso posteriormente em vez de na chamada.

Ainda com Dificuldades?

Se nenhuma das soluções acima funcionar:

  1. Verifique a página de status para incidentes em andamento
  2. Revise suas métricas de request no 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

Atualizado em: 12 de agosto de 2026