Headers de respuesta

Cada response de la API de FourA incluye un conjunto reducido de headers personalizados. Resultan útiles para rastreo, soporte, conciliación de facturación y análisis posterior.

Headers que establece FourA

Header Presente en Descripción
X-FourA-Request-Id Cada response de /api/*, incluidos errores y 401, excepto si FourA no puede leer el body en absoluto (400 Invalid JSON in request body, 413), caso en el que se rechaza antes de asignar un ID Un UUID que identifica esta request. Regístralo en tus logs.
X-FourA-Credits Cada response de /api/* que llegó al backend Créditos consumidos en esta llamada. Se devuelve tanto en caso de éxito como de error (el trabajo se realizó en ambos casos).
X-FourA-Limit Cada 403 o 429 generado por uno de los límites de tu plan Qué límite rechazó la llamada: plan_limit_ seguido de feature, premium, concurrency, rate, browser_daily, credits o bandwidth.
Retry-After Los 429 por límite de plan que se resuelven esperando (concurrencia, rate, créditos, ancho de banda) y el 503 API key check temporarily unavailable Segundos de espera, como un número entero. Coincide con retry_after_seconds en el body de límite de plan y con retryAfter en el 503.
X-FourA-Exit-Class Cada llamada a /api/proxy/ o /api/auto/ que indicó un exitClass y entregó una página, y cada llamada Single o Browser atendida mediante una salida premium premium o standard: la clase de salida que entregó el body. Una llamada a Proxy fallida no entregó nada y no incluye este header.
X-FourA-Browser-Used-Today Cada respuesta de POST /api/browser/ que los límites de tu plan no rechazaron, y cada respuesta de POST /api/auto/ cuya escala envió una request no rechazada Requests de Browser contabilizadas hoy en tu cuenta: consulta más abajo.
X-FourA-Browser-Limit-Per-Day Las mismas respuestas, cuando tu plan establece una cantidad diaria Requests de Browser permitidas por día en tu plan.
X-FourA-Check-Page Responses de Single, Proxy Finder y Browser cuyo body HTTP 200 corresponde a una página de comprobación de bots o de rechazo reconocida por FourA El nombre de la página, por ejemplo amazon-captcha. Esta request no se factura: consulta Request Outcomes.
Content-Type Todas las responses Siempre application/json para el contenedor. El content-type del destino se devuelve dentro del campo headers del contenedor.

X-FourA-Request-Id

Cada llamada a POST /api/auto/, POST /api/single/, POST /api/proxy/ o POST /api/browser/ se etiqueta con un UUID. El header se incluye incluso si falla la autenticación, lo que te permite correlacionar también las llamadas 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
...

Cuándo usarlo

  • Tickets de soporte: incluye el ID de la request y podremos encontrar la llamada exacta en nuestros registros.
  • Tus propios logs: guárdalo junto a la línea de log de tu aplicación. Si una queja de un cliente dice "los datos eran incorrectos a las 14:32", puedes reproducir la request exacta.
  • Rastreo en el dashboard: el mismo ID aparece en el feed de actividad para las keys que administras, de modo que puedes abrir la fila correspondiente e inspeccionar la request y la response capturadas.

Ejemplo: registro en tu 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 el costo en créditos de la llamada que acabas de realizar. Es un medidor, no una factura: el header refleja lo que consumió el trabajo independientemente del resultado. La capa de facturación del dashboard solo descuenta de tu plan los resultados facturables (consulta Resultados de Solicitudes para ver qué resultados son facturables).

Referencia de costos

Engine Base Con unblocker
Single 1 2
Proxy 2 4
Browser 5 10 (cuando se resolvió una defensa)

/api/auto/ cuenta como una sola request en tu dashboard, con un costo en créditos equivalente a la suma de las subllamadas que realizó internamente (un replay simple en un objetivo activo puede completarse en 2; una resolución en frío en un sitio complejo puede consumir mucho más). El valor X-FourA-Credits en la respuesta auto equivale a meta.credits en el body y registra el costo total de la secuencia.

¿Por qué tanto un header como un campo en el body?

El header es práctico: puedes leerlo antes de procesar el body, registrarlo junto a tu línea de request o sumarlo a lo largo de muchas llamadas sin parsear JSON. En Auto, el campo meta.credits del body contiene el mismo número. Los bodies de Single, Proxy y Browser no lo incluyen, por lo que en esas respuestas el header es el único lugar donde leerlo. La fila de Actividad de cada llamada también lo muestra.

X-FourA-Limit

X-FourA-Limit aparece únicamente cuando uno de los límites de tu plan rechazó la llamada. Los rate limits compartidos de la plataforma nunca lo configuran, por lo que este header es la forma más rápida de distinguir "mi plan bloqueó esto" de "FourA está ocupado" sin necesidad de parsear el 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

Dos de los siete valores devuelven un 403 en lugar de un 429: plan_limit_feature (el endpoint o el parámetro exitCountries no están incluidos en tu plan) y plan_limit_premium (exitClass: premium no está incluido en tu plan). Ninguno define Retry-After, ya que esperar no cambia la respuesta.

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

Los siete valores y los campos del body que acompañan a cada uno se encuentran en Rate Limits.

X-FourA-Exit-Class

X-FourA-Exit-Class indica la clase de salida que entregó el body: premium cuando lo hizo una salida premium, standard cuando lo hizo el pool estándar. Aparece en una response de POST /api/proxy/ o POST /api/auto/ que entregó una página siempre que el request haya especificado un exitClass, donde el body incluye el mismo valor (exitClass en Proxy, meta.exitClass en Auto), y en una response de Single o Browser siempre que el proxy que fijaste haya sido una salida premium, donde el body no tiene un campo para ello. Una llamada fallida de Proxy o Auto no entregó nada, por lo que no incluye ni el header ni el 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

El tráfico a través de una salida premium cuenta tanto para tu tráfico premium como para tu ancho de banda total. Se mide en la red e incluye los intentos premium que no devolvieron tu página, por lo que una request respondida con standard aún puede haber usado algo de tráfico premium, en un intento que falló antes de que el pool estándar respondiera. Este header indica la clase que entregó la respuesta, no si se utilizó tráfico premium: la marca premium en una fila de Actividad y la página de Uso y límites muestran lo que se contabilizó. Qué hace exitClass y cuándo se utiliza una salida premium: exitClass.

X-FourA-Browser-Used-Today y X-FourA-Browser-Limit-Per-Day

Estos dos headers incluyen tu límite diario de navegador directamente en la respuesta, los mismos números que muestra la página de Uso y límites, para que puedas monitorearlo sin consultar continuamente el 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

El conteo se reinicia a medianoche UTC y cubre cada clave de tu plan, no solo la que realizó esta llamada. Una request que los límites de tu plan rechazaron no incluye ninguno de los dos headers: su body tiene used_today y limit_per_day en su lugar; consulta Rate Limits.

En POST /api/browser/ el conteo incluye la request que estás leyendo. En POST /api/auto/ es el conteo más alto que recibió la escala mientras se ejecutaba, por lo que puede ir por detrás del día debido a otras requests tuyas que aún se estén ejecutando. Una respuesta de Auto que no envió ninguna request, como la pausa de 120 segundos tras fallos repetidos en un sitio, no incluye ninguno de los dos headers. Lo que una llamada de Auto descontó del conteo está en meta.browserRequests: consulta Smart Fetch.

Comportamiento del caché

La API no establece Cache-Control. Una response puede incluir un ETag débil calculado a partir de su body, pero nada se almacena en caché: cada llamada llega al backend. Si necesitas almacenamiento en caché, agrégalo de tu lado.

Headers de respuesta del destino

Los headers que devolvió el sitio de destino no están en la response de la API de FourA. Se devuelven dentro del envoltorio JSON como el campo headers. Para los endpoints Single y Proxy, este es un array de objetos de headers por salto (una entrada por cada paso de redirección). Para el endpoint Browser, es un objeto plano con los headers de la response final.

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

Si necesitas un header de destino específico, léelo desde el campo headers del envelope, no desde la HTTP response de la llamada a la API en sí.

Actualizado: 5 de noviembre de 2026