Headers de réponse

Chaque réponse de l'API FourA inclut un petit ensemble de headers personnalisés. Ils sont utiles pour le traçage, le support, la réconciliation de facturation et l'analyse post-hoc.

Headers définis par FourA

Header Défini sur Description
X-FourA-Request-Id Chaque réponse /api/*, y compris les erreurs et les 401, à l'exception d'un body que FourA ne peut pas lire du tout (400 Invalid JSON in request body, 413), qui est refusé avant qu'un ID ne soit attribué Un UUID identifiant cette request. Enregistrez-le dans vos logs.
X-FourA-Credits Chaque réponse /api/* ayant atteint le backend Crédits dépensés pour cet appel. Renvoyé en cas de succès comme d'échec (le travail a été effectué dans les deux cas).
X-FourA-Limit Chaque 403 ou 429 déclenché par l'une des limites de votre forfait La limite ayant refusé l'appel : plan_limit_ suivi de feature, premium, concurrency, rate, browser_daily, credits ou bandwidth.
Retry-After Les 429 de limite de forfait qu'une attente permet de résoudre (concurrence, rate limit, crédits, bande passante) et le 503 API key check temporarily unavailable Secondes à attendre, sous forme d'entier. Correspond à retry_after_seconds dans le body d'une limite de forfait et à retryAfter sur le 503.
X-FourA-Exit-Class Chaque appel /api/proxy/ ou /api/auto/ ayant indiqué un exitClass et livré une page, et chaque appel Single ou Browser servi via une sortie premium premium ou standard : la classe de sortie ayant livré le body. Un appel Proxy en échec n'a rien livré et n'en porte aucun.
X-FourA-Browser-Used-Today Chaque réponse POST /api/browser/ non refusée par les limites de votre forfait, et chaque réponse POST /api/auto/ dont l'escalade a envoyé une request non refusée Requests Browser comptabilisées aujourd'hui sur votre compte : voir ci-dessous.
X-FourA-Browser-Limit-Per-Day Les mêmes réponses, lorsque votre forfait définit un nombre quotidien Requests Browser autorisées par jour selon votre forfait.
X-FourA-Check-Page Réponses Single, Proxy Finder et Browser dont le body HTTP 200 est une page de vérification de bot ou de refus reconnue par FourA Le nom de la page, par exemple amazon-captcha. Une telle request n'est pas facturée : voir Request Outcomes.
Content-Type Chaque réponse Toujours application/json pour l'enveloppe. Le content-type de la cible est renvoyé dans le champ headers de l'enveloppe.

X-FourA-Request-Id

Chaque appel à POST /api/auto/, POST /api/single/, POST /api/proxy/ ou POST /api/browser/ est étiqueté avec un UUID. Le header est défini même lorsque l'authentification échoue, ce qui vous permet de corréler également les appels mal configurés.

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

Quand l'utiliser

  • Tickets de support : incluez l'ID de la request pour que nous puissions retrouver l'appel exact dans nos enregistrements.
  • Vos propres logs : stockez-le avec votre ligne de log applicatif. Si un client signale que « les données étaient incorrectes à 14h32 », vous pouvez rejouer la request exacte.
  • Traçage dans le tableau de bord : le même ID apparaît dans le flux d'activité pour les clés que vous gérez, ce qui vous permet d'ouvrir la ligne correspondante et d'inspecter la request et la response capturées.

Exemple : journaliser de votre côté

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 indique le coût en crédits de l'appel que vous venez d'effectuer. C'est un compteur, pas une facture: le header reflète ce que l'opération a consommé, quel que soit le résultat. La couche de facturation du tableau de bord ne décompte de votre forfait que les résultats facturables (consultez Résultats des requêtes pour savoir quels résultats sont facturables).

Référence des coûts

Moteur Base Avec unblocker
Single 1 2
Proxy 2 4
Browser 5 10 (lorsqu'une protection a été résolue)

/api/auto/ représente une seule requête sur votre tableau de bord, avec un coût en crédits équivalant à la somme des sous-appels effectués en interne (un simple rejeu sur une cible chaude peut s'élever à 2; une résolution à froid sur un site complexe peut coûter beaucoup plus). La valeur de X-FourA-Credits sur la réponse auto est égale à meta.credits dans le corps et suit le coût total de la séquence.

Pourquoi à la fois un header et un champ dans le corps?

Le header est pratique: vous pouvez le lire avant de parser le corps, le consigner à côté de votre ligne de requête ou l'additionner sur de nombreux appels sans parser le JSON. Avec Auto, le champ meta.credits du corps contient la même valeur. Les corps de Single, Proxy et Browser ne le contiennent pas; sur ces réponses, le header est donc le seul endroit où le lire. La ligne Activité de chaque appel l'affiche également.

X-FourA-Limit

X-FourA-Limit apparaît uniquement lorsqu'une des limites de votre forfait a refusé l'appel. Les rate limits partagés de la plateforme ne le définissent jamais, ce header est donc le moyen le plus rapide de distinguer "mon forfait a bloqué ceci" de "FourA est occupé" sans parser le corps.

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

Deux des sept valeurs sont renvoyées avec une erreur 403 plutôt qu'un 429 : plan_limit_feature (l'endpoint ou le paramètre exitCountries n'est pas inclus dans votre forfait) et plan_limit_premium (exitClass: premium n'est pas inclus dans votre forfait). Aucun des deux ne définit Retry-After, car attendre ne changera pas la réponse.

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

Les sept valeurs et les champs de corps associés sont détaillés dans Rate Limits.

X-FourA-Exit-Class

X-FourA-Exit-Class indique la classe de sortie ayant fourni le corps : premium pour une sortie premium, standard pour le pool standard. Il figure sur une réponse POST /api/proxy/ ou POST /api/auto/ ayant renvoyé une page dès lors que la requête précisait un exitClass, où le corps contient la même valeur (exitClass sur Proxy, meta.exitClass sur Auto), ainsi que sur une réponse Single ou Browser dès lors que le proxy épinglé était une sortie premium, où le corps ne comporte aucun champ dédié. Un appel Proxy ou Auto en échec n'a rien renvoyé ; il ne contient donc ni l'en-tête ni le champ.

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

Le trafic passant par une sortie premium est décompté de votre trafic premium ainsi que de votre bande passante totale. Il est mesuré sur le réseau et inclut les tentatives premium qui n'ont pas renvoyé votre page. Par conséquent, une requête répondue avec standard peut tout de même avoir consommé du trafic premium, lors d'une tentative ayant échoué avant que le pool standard ne réponde. Cet en-tête indique la classe qui a délivré la réponse, et non si du trafic premium a été utilisé : la mention premium sur une ligne d'Activité et la page Utilisation et limites indiquent ce qui a été comptabilisé. Pour comprendre le fonctionnement de exitClass et savoir quand une sortie premium est utilisée : exitClass.

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

Ces deux en-têtes transmettent votre quota quotidien de navigateur directement dans la réponse, avec les mêmes valeurs que celles affichées sur la page Utilisation et limites, ce qui vous permet de le suivre sans interroger le tableau de bord.

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

Le décompte se réinitialise à minuit UTC et couvre chaque clé de votre forfait, pas seulement celle qui a effectué cet appel. Une requête refusée par les limites de votre forfait ne comporte aucun de ces deux en-têtes : son corps contient used_today et limit_per_day à la place, voir Rate Limits.

Sur POST /api/browser/, le décompte inclut la requête que vous lisez. Sur POST /api/auto/, il s'agit du décompte le plus élevé reçu par l'algorithme d'escalade pendant son exécution, il peut donc être inférieur au total de la journée en raison de vos autres requêtes en cours. Une réponse Auto qui n'a envoyé aucune requête, comme la pause de 120 secondes après des échecs répétés sur un site, ne porte aucun de ces en-têtes. Ce qu'un appel Auto a déduit du décompte se trouve dans meta.browserRequests : voir Smart Fetch.

Comportement du cache

L'API ne définit pas Cache-Control. Une réponse peut porter un ETag faible calculé à partir de son corps, mais rien n'est mis en cache : chaque appel atteint le backend. Si vous avez besoin de mise en cache, implémentez-la de votre côté.

En-têtes de réponse cibles

Les en-têtes renvoyés par le site cible ne figurent pas sur la réponse de l'API FourA. Ils sont retournés dans l'enveloppe JSON sous le champ headers. Pour les endpoints Single et Proxy, il s'agit d'un tableau d'objets d'en-têtes par saut (une entrée par étape de redirection). Pour l'endpoint Browser, il s'agit d'un objet plat contenant les en-têtes de la réponse finale.

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

Si vous avez besoin d'un header cible spécifique, lisez-le depuis le champ headers de l'enveloppe, et non depuis la response HTTP de l'appel API lui-même.

Mis à jour : 5 novembre 2026