Headers de response

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 429s 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.
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.

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 para chaves que você gerencia, permitindo abrir a linha correspondente e inspecionar a request e a response capturadas.

Exemplo: log do seu lado

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()
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 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 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.

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.

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 e a página Usage & Limits mostram o que foi contabilizado. O que exitClass faz e quando uma saída premium é usada: 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, 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.

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.

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.

{
  "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.

Atualizado em: 5 de novembro de 2026