Response Headers

Toda response da API FourA inclui um pequeno conjunto de custom headers. Eles são úteis para rastreamento, suporte, conciliação de faturamento e análises posteriores.

Headers definidos pelo FourA

X-FourA-Request-Id

Cada chamada para POST /api/auto/, POST /api/single/, POST /api/proxy/ ou POST /api/browser/ é marcada com um UUID. O header é definido mesmo quando a autenticação falha, para que você possa correlacionar também chamadas mal configuradas.

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

• Chamados de suporte: inclua o ID da requisição e podemos encontrar a chamada exata em nossos registros.
• Seus próprios logs: armazene-o junto à linha de log da sua aplicação. Se a reclamação de um cliente disser "os dados estavam incorretos às 14:32", você pode reproduzir a requisição exata.
• Rastreamento no painel: o mesmo ID aparece no feed de Atividade para as chaves que você gerencia, permitindo abrir a linha correspondente e inspecionar a requisição e a resposta 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 o trabalho consumiu, independentemente do resultado. A camada de faturamento do painel conta apenas resultados faturáveis contra o seu plano (consulte Request Outcomes para saber quais resultados são faturáveis).

Referência de custo

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

Por que incluir tanto um header quanto um campo no body?

O header é prático: você pode lê-lo antes de analisar o body, registrá-lo em log junto à linha da sua request ou somá-lo entre várias chamadas sem parsing de JSON. O meta.credits do body (Auto) ou os metadados por engine (painéis Single, Proxy, Browser) contêm o mesmo número, mas legível dentro do envelope de response.

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, portanto o header é a forma mais rápida de diferenciar "meu plano barrou isso" de "FourA está ocupado" sem analisar o 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 está no seu plano) e plan_limit_premium (exitClass: premium não está no seu plano). Nenhum dos dois define Retry-After, pois aguardar 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/ que entregou uma página sempre que a request indicou um exitClass, onde o body contém o mesmo valor, 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 um campo para isso. Uma chamada de Proxy com falha não entregou nada, portanto não contém nem 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 meio de uma saída premium é contabilizado tanto no seu tráfego premium quanto na sua largura de banda total. Ele é medido na rede e inclui tentativas premium que não retornaram sua página, portanto, uma request respondida com standard ainda pode ter consumido algum tráfego premium, em uma tentativa que falhou antes do pool padrão responder. Este header indica a classe que entregou a resposta, não se o tráfego premium foi utilizado: a marcação premium em uma linha de Atividade e a página de Uso e Limites mostram o que foi contabilizado. Para saber o que exitClass faz e quando uma saída premium é usada: exitClass.

Comportamento de Cache

A API não define Cache-Control ou ETag nas responses. Cada chamada atinge o backend. Se você precisar de cache, implemente-o do seu lado.

Headers de Resposta do 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, este é 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 request ID
• Rate Limits: O que cada valor de X-FourA-Limit significa