Docs › Solução de problemas › Problemas Comuns

Problemas Comuns

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

Conteúdo Vazio ou Incompleto

Sintoma: A API retorna um 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: Alterne do endpoint single para o endpoint browser. 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 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 a request como automatizada e a bloqueou.

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

Erros de Timeout

Sintoma: As requests falham com um erro de timeout.

Causa: A página de destino demora mais 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 browser, verifique também 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 de "rate limit exceeded".

Causa: Você excedeu seu limite de requests por minuto (RPM). Isso é diferente dos limites de concorrência (veja 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 concorrência atingido. Você tem muitas requests simultâneas em execução. Isso é diferente do 429, que limita as requests por minuto. Com o 503, você não excedeu seu RPM, mas atingiu o limite máximo de requests que podem ser executadas 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 os segundos indicados em retryAfter 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ê estiver atingindo os limites de concorrência 503 regularmente, reduza o número de requests paralelas no seu pipeline de scraping ou verifique o limite de concorrência do seu plano no Dashboard.

Erros de Autenticação 401

Sintoma: Todas as requests retornam 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 ou quebras de linha extras na sua chave de API
  3. Crie uma nova chave no Dashboard se a atual puder estar comprometida

HTML Inesperado em Vez de JSON

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

Causa: A página de destino pode servir conteúdos diferentes com base nos headers.

Solução: Adicione um header Accept e ative o unblocker para obter headers de browser 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 responses em JSON.

Ainda com Problemas?

Se nenhuma das soluções acima funcionar:

  1. Verifique a status page para ver se há incidentes em andamento
  2. Revise as métricas das suas requests no Dashboard
  3. Entre em contato com o suporte em support@foura.ai enviando os detalhes da sua request

Próximos Passos

Atualizado em: 27 de abril de 2026