Docs › Referência API › Resultados de Requests

Resultados de Requests

Cada request para a API do FourA é classificado em exatamente um resultado. O resultado é calculado uma vez no momento do request e registrado na sua chave de API. Seu dashboard, feed de atividades e faturamento leem o mesmo campo.

Apenas success é faturável.

Os Sete Resultados

Resultado Camada O que significa
success n/a Uma response válida foi entregue. Conta contra sua cota faturável.
application_error target O target retornou HTTP 200, mas o corpo continha um campo de erro.
application_fail target O target retornou um status não-2xx que suas regras de validate não aceitaram, ou nenhuma response.
client_error caller Seu request foi rejeitado antes de sair do FourA. Parâmetros incorretos, valor de proxy malformado, URL protegida por SSRF.
rate_limit FourA Seu limite de RPM ou de concorrência foi atingido.
service_error FourA O backend retornou um 5xx, ou seu corpo não era um JSON válido.
service_fail FourA Falha de rede: timeout, conexão recusada, erro de DNS, desconexão do cliente.

A coluna de camada indica quem é o responsável:

  • Os resultados de target dizem respeito ao site que você chamou. Seu request chegou ao FourA corretamente, e o FourA chegou ao target corretamente. O próprio target retornou um erro.
  • Os resultados de caller significam que seu request nunca teve chance. Corrija o formato do request.
  • Os resultados do FourA são de nossa responsabilidade. Tente novamente e verifique a página de status se eles persistirem.

Um site target retornando 403 é classificado como application_fail, não client_error. Sua chamada estava bem formatada. O site apenas recusou.

O Success considera o validate

Sem o validate, a API marca um request como success apenas quando o target retorna HTTP 200.

Com o validate, o success segue as regras que você declarou. Se você disser à API que 200 e 403 são aceitáveis para um determinado request, um 403 retorna como success. O corpo ainda chega até você inalterado.

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://target.example/feed",
    "validate": {
      "status": { "accept": [200, 403] }
    }
  }'

Nesta chamada, uma response 403 conta como success e é faturada como um request. Uma response 500 conta como application_fail e não é faturada.

A mesma lógica se aplica a validate.headers e validate.data. Qualquer response que o motor aceite contra suas regras retorna como success, independentemente do status HTTP.

Implicações de Faturamento

Resultado Faturável Conta para a cota
success Sim Sim
application_error Não Não
application_fail Não Não
client_error Não Não
rate_limit Não Não
service_error Não Não
service_fail Não Não

Apenas os requests que entregaram os dados solicitados são faturados. Falhas no lado do FourA, no lado do target ou no seu próprio lado são gratuitas.

Lendo Resultados no Dashboard

Cada request que sua chave de API faz aparece no feed de Atividade com seu rótulo de resultado. As páginas de Métricas e Visão Geral agregam o mesmo campo para gráficos de rosca e linhas do tempo.

Ao filtrar a Atividade por resultado, você também pode focar em um único produto (Single, Proxy, Browser) para ver se uma classe de falha é específica de um endpoint.

Heurísticas de Retry

Uma política de retry inicial baseada em resultados:

Resultado Seguro para retry? Quando
success n/a Você já tem a response.
application_error Às vezes Leia o corpo de erro do target. Alguns são temporários, a maioria não.
application_fail Às vezes Se o target estiver aplicando rate limit, diminua o ritmo. Se estiver bloqueando você, mude para o endpoint Proxy ou Browser.
client_error Não O request falhará novamente da mesma forma. Corrija a entrada.
rate_limit Sim Respeite o retryAfter do corpo da response.
service_error Sim Backoff exponencial curto.
service_fail Sim O mesmo que service_error.

Relacionado

Atualizado em: 18 de junho de 2026
← Endpoint de Inspeção Headers de Response →