# Headers de response

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

Cada response da API do FourA inclui um pequeno conjunto de headers personalizados. Eles são úteis para rastreamento, suporte, conciliação de faturamento e análise posterior.

## Headers Definidos pelo FourA

| Header | Definido em | Descrição |
|--------|--------|-------------|
| `X-FourA-Request-Id` | Toda response `/api/*`, incluindo erros e 401s, exceto um body que o FourA não consiga ler de forma alguma (`400 Invalid JSON in request body`, `413`), o qual é recusado antes que um ID seja atribuído | Um UUID que identifica esta request. Registre-o em seus logs. |
| `X-FourA-Credits` | Toda response `/api/*` que alcançou o backend | Créditos gastos nesta chamada. Retornado em caso de sucesso e de falha (o trabalho foi realizado de qualquer forma). |
| `X-FourA-Limit` | Todo `403` ou `429` gerado por um dos limites do seu plano | Qual limite recusou a chamada: `plan_limit_` seguido por `feature`, `premium`, `concurrency`, `rate`, `browser_daily`, `credits` ou `bandwidth`. |
| `Retry-After` | `429`s de limite de plano que uma espera resolve (concorrência, taxa, créditos, largura de banda) e o 503 `API key check temporarily unavailable` | Segundos de espera, como um número inteiro. Corresponde a `retry_after_seconds` em um body de limite de plano e a `retryAfter` no 503. |
| `X-FourA-Exit-Class` | Toda chamada `/api/proxy/` ou `/api/auto/` que indicou um `exitClass` e entregou uma página, e toda chamada Single ou Browser atendida por meio de uma saída premium | `premium` ou `standard`: a classe de saída que entregou o body. Uma chamada de Proxy que falhou não entregou nada e não traz nenhum. |
| `X-FourA-Browser-Used-Today` | Toda resposta `POST /api/browser/` que os limites do seu plano não recusaram, e toda resposta `POST /api/auto/` cuja sequência enviou uma request não recusada | Requests de Browser contabilizadas hoje na sua conta: veja abaixo. |
| `X-FourA-Browser-Limit-Per-Day` | As mesmas respostas, quando o seu plano estabelece um limite diário | Requests de Browser que o seu plano permite por dia. |
| `X-FourA-Check-Page` | Responses de Single, Proxy Finder e Browser cujo body HTTP 200 seja uma verificação de bot ou página de recusa reconhecida pelo FourA | O nome da página, por exemplo `amazon-captcha`. Uma request como essa não é cobrada: veja [Resultados de Requests](https://foura.ai/docs/api/outcomes). |
| `Content-Type` | Toda response | Sempre `application/json` para o envelope. O content-type de destino retorna dentro do campo `headers` do envelope. |

## X-FourA-Request-Id

Cada chamada para `POST /api/auto/`, `POST /api/single/`, `POST /api/proxy/` ou `POST /api/browser/` é identificada com um UUID. O header é definido mesmo quando a autenticação falha, permitindo que você correlacione também chamadas configuradas incorretamente.

```bash
curl -i -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://example.com"}'
```

```
HTTP/1.1 200 OK
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
X-FourA-Credits: 2
Content-Type: application/json
...
```

### Quando usar

- **Tickets de suporte**: inclua o ID da request e poderemos localizar a chamada exata em nossos registros.
- **Seus próprios logs**: armazene-o junto à linha de log da sua aplicação. Se uma reclamação de cliente disser que "os dados estavam incorretos às 14:32", você poderá reproduzir a request exata.
- **Rastreamento no painel**: o mesmo ID aparece no [feed de atividades](https://foura.ai/docs/dashboard/activity-log) para chaves que você gerencia, permitindo abrir a linha correspondente e inspecionar a request e a response capturadas.

### Exemplo: log do seu lado

```python
import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    resp = requests.post(
        "https://eu.api.foura.ai/api/single/",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json={"method": "GET", "url": url},
    )
    request_id = resp.headers.get("X-FourA-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()
```

```javascript
async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-FourA-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}
```

## X-FourA-Credits

`X-FourA-Credits` informa o custo em créditos da chamada que você acabou de fazer. É um medidor, não uma fatura: o header reflete o que a execução consumiu, independentemente do resultado. A camada de faturamento do dashboard apenas contabiliza resultados faturáveis contra o seu plano (consulte [Request Outcomes](https://foura.ai/docs/api/outcomes) para saber quais resultados são faturáveis).

### Referência de custos

| Engine | Base | Com `unblocker` |
|--------|------|------------------|
| Single | 1 | 2 |
| Proxy | 2 | 4 |
| Browser | 5 | 10 (quando uma defesa foi resolvida) |

`/api/auto/` é uma única request no seu dashboard, com um custo em créditos que é a soma das subchamadas feitas internamente (um único replay em um alvo quente pode terminar em 2; uma resolução a frio em um site difícil pode consumir muito mais). O valor de `X-FourA-Credits` na resposta do Auto é igual a `meta.credits` no body e rastreia o custo total da sequência.

### Por que um header e um campo no body?

O header é conveniente: você pode lê-lo antes de fazer o parse do body, registrá-lo em log junto com a linha da sua request ou somá-lo em várias chamadas sem parsing de JSON. No Auto, o `meta.credits` do body contém o mesmo número. Os bodies do Single, Proxy e Browser não o incluem, portanto, nessas respostas, o header é o único local para lê-lo. A linha de [Activity](https://foura.ai/docs/dashboard/activity-log) de cada chamada também o exibe.

## X-FourA-Limit

`X-FourA-Limit` aparece apenas quando um dos limites do seu plano recusou a chamada. Os rate limits compartilhados da plataforma nunca o definem, tornando o header a maneira mais rápida de diferenciar "meu plano bloqueou isto" de "o FourA está ocupado" sem precisar fazer o parse do body.

```
HTTP/1.1 429 Too Many Requests
X-FourA-Limit: plan_limit_concurrency
Retry-After: 1
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
Content-Type: application/json
```

Dois dos sete valores retornam 403 em vez de 429: `plan_limit_feature` (o endpoint ou o parâmetro `exitCountries` não faz parte do seu plano) e `plan_limit_premium` (`exitClass: premium` não faz parte do seu plano). Nenhum dos dois define `Retry-After`, pois esperar não altera a resposta.

```python
STOP_ON = {
    "plan_limit_feature", "plan_limit_premium",
    "plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth",
}

resp = requests.post(url, headers=headers, json=payload)

limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
    stop_the_run(limit)                # hours or days away, not seconds
elif limit:
    time.sleep(int(resp.headers.get("Retry-After", 1)))
```

Os sete valores e os campos do body que acompanham cada um estão em [Rate Limits](https://foura.ai/docs/api/rate-limits).

## X-FourA-Exit-Class

`X-FourA-Exit-Class` indica a classe de saída que entregou o body: `premium` quando foi uma saída premium, `standard` quando foi o pool padrão. Ele aparece em uma response `POST /api/proxy/` ou `POST /api/auto/` que entregou uma página sempre que a request especificou um `exitClass`, onde o body contém o mesmo valor (`exitClass` no Proxy, `meta.exitClass` no Auto), e em uma response Single ou Browser sempre que o `proxy` que você fixou for uma saída premium, onde o body não possui campo para isso. Uma chamada com falha no Proxy ou Auto não entrega nada, portanto não contém o header nem o campo.

```
HTTP/1.1 200 OK
X-FourA-Exit-Class: premium
X-FourA-Credits: 2
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
```

O tráfego por uma saída premium conta tanto para o seu tráfego premium quanto para a sua largura de banda total. Ele é medido na rede e inclui tentativas premium que não retornaram a sua página, portanto uma request respondida com `standard` ainda pode ter consumido tráfego premium, em uma tentativa que falhou antes do pool padrão responder. Esse header identifica a classe que entregou a resposta, não se o tráfego premium foi utilizado: a marcação **premium** em uma linha de [Activity](https://foura.ai/docs/dashboard/activity-log) e a página [Usage & Limits](https://foura.ai/docs/dashboard/quota) mostram o que foi contabilizado. O que `exitClass` faz e quando uma saída premium é usada: [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

## X-FourA-Browser-Used-Today e X-FourA-Browser-Limit-Per-Day

Estes dois headers trazem o seu limite diário de browser na própria resposta, com os mesmos números exibidos na página [Usage & Limits](https://foura.ai/docs/dashboard/quota), permitindo que você acompanhe o uso sem precisar consultar o dashboard.

```
HTTP/1.1 200 OK
X-FourA-Browser-Used-Today: 1250
X-FourA-Browser-Limit-Per-Day: 5000
X-FourA-Credits: 47
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
```

A contagem reinicia a meia-noite UTC e cobre todas as chaves do seu plano, não apenas a que fez esta chamada. Uma request recusada pelos limites do seu plano não inclui nenhum dos headers: seu corpo contém `used_today` e `limit_per_day` em vez disso, veja [Rate Limits](https://foura.ai/docs/api/rate-limits).

No `POST /api/browser/` a contagem inclui a request que você está lendo. No `POST /api/auto/` é a maior contagem fornecida a escada durante a execução, portanto, pode ficar defasada em relação ao dia pelas suas outras requests ainda em execução. Uma resposta Auto que não enviou nenhuma request, como a pausa de 120 segundos após falhas repetidas em um site, não contém nenhum dos headers. O consumo que uma chamada Auto debitou da contagem está em `meta.browserRequests`: veja [Smart Fetch](https://foura.ai/docs/guides/smart-fetch).

## Comportamento do Cache

A API não define `Cache-Control`. Uma response pode conter uma `ETag` fraca calculada a partir do seu corpo, mas nada é armazenado em cache: toda chamada atinge o backend. Se você precisar de cache, adicione-o do seu lado.

## Headers da Response de Destino

Os headers retornados pelo site de destino não estão na response da API FourA. Eles retornam dentro do envelope JSON como o campo `headers`. Para os endpoints Single e Proxy, isso é um array de objetos de header por salto (uma entrada por etapa de redirecionamento). Para o endpoint Browser, é um objeto simples com os headers da response final.

```json
{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}
```

Se você precisar de um header de destino específico, leia-o do campo `headers` do envelope, não da resposta HTTP da chamada de API em si.

## Relacionado

- [API Endpoints](https://foura.ai/docs/api/endpoints): Formatos de envelope de request e response
- [API Errors](https://foura.ai/docs/api/errors): Como as respostas de erro são estruturadas
- [Request Outcomes](https://foura.ai/docs/api/outcomes): Quais resultados são faturáveis
- [Activity Log](https://foura.ai/docs/dashboard/activity-log): Histórico por request indexado por ID de request
- [Rate Limits](https://foura.ai/docs/api/rate-limits): O que cada valor de `X-FourA-Limit` significa
