Resultados de Requests

Cada request para a API FourA é classificado em exatamente um resultado, e o mesmo vale para cada túnel pela porta proxy. O resultado é calculado uma vez, ao final da chamada, e registrado na credencial que a realizou. Seu painel, feed de atividades e faturamento leem o mesmo campo.

Apenas success consome créditos. O tráfego premium é contabilizado separadamente dos créditos e não segue o resultado: veja Implicações no Faturamento.

Os Sete Resultados

Estes são os sete resultados possíveis de um request. Um túnel utiliza cinco deles: veja Túneis Usam o Mesmo Vocabulário abaixo.

Resultado Camada O que significa
success n/a Uma response válida foi entregue. Conta no seu limite faturável.
application_error target O destino retornou HTTP 200, mas o body continha um campo de erro, ou o body é uma página de verificação de bot ou de recusa reconhecida pela FourA.
application_fail target O destino retornou um status diferente de 200 que suas regras de validate não aceitaram ou para o qual você não enviou validate, ou nenhuma response, incluindo um nome de host de destino que não pode ser resolvido.
client_error caller Seu request foi rejeitado antes de sair da FourA. Parâmetros inválidos, valor de proxy malformado, URL protegida contra SSRF.
rate_limit FourA O request foi recusado antes de ser executado: por um dos limites do seu plano (um 403 para um endpoint ou parâmetro não incluído no plano, um 429 por cota esgotada) ou pelo limite compartilhado de RPM ou concorrência da plataforma.
service_error FourA O motor respondeu com um erro de servidor ou o body não continha um JSON válido.
service_fail FourA A própria rede da FourA falhou: o motor não respondeu a tempo, a conexão caiu ou você se desconectou.

A coluna de camada mostra de quem é a responsabilidade:

  • Resultados de target dizem respeito ao site que você chamou. Seu request chegou perfeitamente à FourA, e a FourA acessou o destino normalmente. O próprio destino retornou um erro.
  • Resultados de caller significam que seu request não tinha como funcionar. Corrija o formato do request.
  • Resultados de FourA são responsabilidade nossa. Tente novamente e consulte a página de status se persistirem.

Um site de destino que retorna 403 é categorizado como application_fail, e não client_error. Sua chamada foi bem estruturada. O site apenas recusou.

Como é uma Chamada com Falha

Uma chamada que alcançou a FourA e foi executada retorna como HTTP 200, independentemente do que aconteceu depois. Apenas uma recusa antes da busca (400, 401, 403, 413, 429) ou uma falha do lado da FourA (5xx) usa outro status HTTP. Portanto, o resultado é lido a partir do body, e não do status de transporte.

Body O que aconteceu Resultado
status: 200, headers, data, sem error A página foi entregue. success
status diferente de 200, headers, data, sem error O destino respondeu e você não enviou validate. A resposta está em data. application_fail
status diferente de 200, headers, data e error O destino respondeu e suas regras validate o rejeitaram, por exemplo Status 404 is not in accept list 200. application_fail
status: 200, headers, data e error O destino respondeu HTTP 200 e suas regras validate o rejeitaram, por exemplo Data not in accept list ["product"]. application_error
error e total_time apenas, sem status, sem data O destino nunca respondeu com HTTP: o limite de redirecionamento foi atingido (Number of redirects hit maximum amount), a conexão ou a leitura expirou, a conexão foi redefinida ou a resposta estava vazia. O texto é o próprio motivo do mecanismo. application_fail
status: 0 e error, nada mais O nome do host não pode ser resolvido: could not resolve <host>: <reason>. Nenhum mecanismo foi executado e, no Auto, não há meta. Tentar novamente não mudará isso até que o DNS mude. application_fail

Um loop de redirecionamento, como a quinta linha o vê:

{
  "error": "Number of redirects hit maximum amount",
  "total_time": 0.808
}

Em POST /api/proxy/, uma chamada que esgota as tentativas traz error: Download maxTry limit reached e um attemptReport com as contagens (consulte API Errors). Em POST /api/auto/, uma ladder que foi executada e falhou traz status, error, attempts, um attemptReport com as causas, e meta.rung definido como fail.

X-FourA-Credits relata o trabalho realizado, mesmo em caso de falha. O faturamento contabiliza apenas success, portanto nenhum dos formatos com falha acima é cobrado.

O sucesso reconhece validate

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

Com validate, o sucesso segue as regras que você declarou. Se você informar à API que 200 e 403 são ambos aceitáveis para uma determinada request, um 403 retorna como success. O body ainda chega até você sem alterações.

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 resposta 403 conta como success e é cobrada como uma request. Uma resposta 500 conta como application_fail e não é cobrada.

A mesma lógica se aplica a validate.headers e validate.data. Qualquer resposta que o mecanismo aceitar de acordo com suas regras retorna como success, independentemente do status HTTP.

Uma resposta nunca é success, com ou sem validate: um HTTP 200 cujo corpo seja uma página de verificação de bot reconhecida pela FourA, como uma tarefa de verificação visual ou uma página que apenas solicita que o navegador execute JavaScript, ou uma página de recusa que um site entrega com HTTP 200. Essa request é application_error e não é faturada. O corpo ainda chega até você inalterado, e o header X-FourA-Check-Page identifica a página.

Implicações de faturamento

Outcome Billable Counts toward quota
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 requests que entregaram os dados solicitados são faturadas. Falhas no lado da FourA, no lado do destino ou no seu próprio lado são gratuitas.

A tabela refere-se a créditos. O tráfego premium é contabilizado separadamente: uma request que tentou um premium exit contabiliza o tráfego transportado por essa tentativa, qualquer que seja o resultado, pois o exit foi utilizado de qualquer forma. Uma tentativa que ainda estava em execução quando outro exit respondeu é interrompida imediatamente, e o tráfego transportado até então também é contabilizado.

O tráfego padrão também não depende do resultado: em um plano com limite de largura de banda, o tráfego de cada request é contabilizado para esse limite. Uma request recusada por um dos limites do seu próprio plano não contabiliza tráfego.

Túneis usam o mesmo vocabulário

Um túnel por meio da proxy port também termina em um desses resultados, portanto um único conjunto de rótulos abrange ambos os produtos. Apenas cinco dos sete podem ocorrer, pois os dois resultados target exigem que a FourA tenha visto a resposta do destino, e a resposta de um túnel é o seu próprio tráfego criptografado.

Outcome On a tunnel, this means
success O túnel foi aberto e sua ferramenta o recebeu.
client_error A FourA não abrirá esse túnel: um endereço privado ou reservado, ou uma porta que ela não atende.
rate_limit Um dos limites do seu plano foi atingido (túneis abertos simultaneamente, aberturas de túnel por minuto, tráfego padrão do período, tráfego premium que você não possui), ou a própria porta estava em sua capacidade máxima ou taxa de abertura limite.
service_error A FourA não tinha saída disponível para o que você solicitou. Geralmente temporário.
service_fail O destino não pôde ser alcançado através de nenhuma saída tentada pela FourA: DNS, timeout, conexão recusada.
application_error Nunca ocorre em um túnel.
application_fail Nunca ocorre em um túnel.

Uma recusa também traz um motivo curto, e o painel o exibe nos seus próprios termos em vez dos nossos. Uma opção que a FourA não pode atender é respondida com 400 na própria conexão e não grava nenhuma linha, portanto nunca aparece aqui.

Motivo na tela O que esgotou
port not in plan Seu plano não inclui a porta de proxy
tunnels at once Todos os túneis simultâneos permitidos pelo seu plano estavam em uso
openings per minute As aberturas de túnel do seu plano para este minuto foram esgotadas
traffic used up O tráfego do seu plano para este período foi esgotado
premium not available O tráfego premium não está disponível no seu plano no momento
port was full A porta em si estava com capacidade máxima ou no limite de taxa de abertura. Tente novamente em instantes.
port not served A FourA não abre túneis para essa porta
private address Endereços privados e reservados não podem ser alcançados

Nada em relação a um túnel é cobrado em créditos, porque um túnel não possui uma requisição para a qual cobrar um crédito. Em vez disso, a porta faz a medição por bytes. Consulte Como seu plano é medido.

Leitura dos resultados no painel

Cada requisição feita pela sua chave de API aparece no feed de Atividade com seu rótulo de resultado. As páginas 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 endpoint (Auto, Single, Proxy Finder, Browser) para verificar se uma classe de falha é específica de um deles. Mude o Produto da página para Proxy e as mesmas opções de resultado filtram seus túneis.

Heurísticas de repetição

Uma política inicial de repetição baseada em resultados:

Resultado Repetição segura? Quando
success n/d Você tem a resposta.
application_error Às vezes Leia o corpo de erro do destino. Alguns são temporários, a maioria não. Se X-FourA-Check-Page estiver definido, o site exibiu uma página de verificação: envie a URL para Auto, que trata uma página de verificação como uma etapa a ser superada, e não como a resposta final.
application_fail Às vezes Se o destino estiver aplicando rate limit, reduza a frequência. Se estiver bloqueando você, mude para o endpoint Proxy ou Browser.
client_error Não A requisição falhará novamente da mesma maneira. Corrija os dados de entrada.
rate_limit Depende Respeite o tempo de espera informado na resposta: Retry-After, retry_after_seconds ou retryAfter. Em plan_limit_browser_daily, pare até a meia-noite UTC; em plan_limit_credits ou plan_limit_bandwidth, pare até resets_at; em plan_limit_feature ou plan_limit_premium, altere a requisição.
service_error Sim Backoff exponencial curto.
service_fail Sim O mesmo que service_error.
  • API Errors: Respostas de erro no nível HTTP
  • Proxy Port: Os status codes retornados quando um túnel é recusado
  • Rate Limits: O que aciona o rate_limit e os dois formatos de retorno
  • Metrics: Onde você vê os resultados detalhados
  • Activity Log: Histórico de resultados por request
Atualizado em: 11 de novembro de 2026