Problemas comuns
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:
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:
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.
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):
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.
{
"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 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 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:
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 mostra o padrão, e Uso e limites no 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:
- 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 capacityno campoerror. Isso geralmente se resolve em segundos. - Serviço temporariamente desativado. Uma janela de manutenção está em andamento.
Service disabledno campoerror. - A FourA não consegue verificar sua chave no momento.
API key check temporarily unavailableno campoerror, comRetry-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:
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:
{
"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.
401 Erros de Autenticação
Sintoma: Toda requisição retorna 401 Unauthorized.
Checklist:
- Verifique se o header é
X-API-Key: YOUR_API_KEY(e nãoAuthorization: BearerouApi-Key) - Verifique se há espaços em branco ou quebras de linha extras na sua chave de API
- Crie uma nova chave a partir do 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 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.
{ "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 (/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:
{
"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.
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 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.
{
"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:
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.
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:
- Verifique a página de status para incidentes em andamento
- Analise as métricas de suas requests no Dashboard
- Entre em contato com o suporte em support@foura.ai com os detalhes da sua request (inclua o
X-FourA-Request-Idda resposta que falhou)
Próximos passos
- Tratamento de erros: Referência de códigos de erro da API
- Rate Limits: Todos os limites de planos e da plataforma, com campos
- Resultados de requests: Como os resultados classificam o que aconteceu
- Verificações de site: O que o campo
defenseindica - Escolhendo o endpoint correto: Escolha a melhor abordagem para o seu destino
- Visão geral do Dashboard: Monitore suas requests