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.
Relacionado
- API Endpoints: Formatos de envelope de request e response
- API Errors: Como as respostas de erro são estruturadas
- Request Outcomes: Quais resultados são faturáveis
- Activity Log: Histórico por request indexado por ID de request
- Rate Limits: O que cada valor de
X-FourA-Limitsignifica