# Resultados de Requests

> URL: https://foura.ai/pt/docs/api/outcomes
> Updated: 2026-11-11
> Index: https://foura.ai/llms.txt

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](#billing-implications).

## 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](#tunnels-use-the-same-vocabulary) 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](https://updates.foura.ai/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ê:

```json
{
  "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](https://foura.ai/docs/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.

```bash
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`](https://foura.ai/docs/api/response-headers) 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](https://foura.ai/docs/api/endpoints#exitclass) 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](https://foura.ai/docs/api/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](https://foura.ai/docs/guides/plans-and-metering).

## Leitura dos resultados no painel

Cada requisição feita pela sua chave de API aparece no feed de [Atividade](https://foura.ai/docs/dashboard/activity-log) com seu rótulo de resultado. As páginas [Métricas](https://foura.ai/docs/dashboard/metrics) e [Visão geral](https://foura.ai/docs/dashboard/overview) 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](https://foura.ai/docs/api/errors): Respostas de erro no nível HTTP
- [Proxy Port](https://foura.ai/docs/api/proxy-port): Os status codes retornados quando um túnel é recusado
- [Rate Limits](https://foura.ai/docs/api/rate-limits): O que aciona o `rate_limit` e os dois formatos de retorno
- [Metrics](https://foura.ai/docs/dashboard/metrics): Onde você vê os resultados detalhados
- [Activity Log](https://foura.ai/docs/dashboard/activity-log): Histórico de resultados por request
