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. |
Relacionado
- 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_limite os dois formatos de retorno - Metrics: Onde você vê os resultados detalhados
- Activity Log: Histórico de resultados por request