En-têtes de réponse

Chaque réponse de l'API FourA comprend un petit ensemble d'en-têtes personnalisés. Ils sont utiles pour le traçage, le support, la réconciliation de facturation et l'analyse a posteriori.

Headers FourA Sets

X-FourA-Request-Id

Chaque appel à POST /api/auto/, POST /api/single/, POST /api/proxy/ ou POST /api/browser/ est associé à un UUID. L'en-tête est défini même en cas d'échec d'authentification, 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 logs.
• Vos propres logs : enregistrez-le à côté de votre ligne de log applicatif. Si une réclamation client indique « les données étaient incorrectes à 14:32 », vous pouvez rejouer la request exacte.
• Traçage dans le tableau de bord : le même ID apparaît dans le flux Activity 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 : log 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 : l'en-tête reflète ce que le travail 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 (voir Request Outcomes pour savoir quels résultats sont facturables).

Référence des coûts

/api/auto/ représente une seule requête sur votre tableau de bord, avec un coût en crédits égal à 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 difficile peut coûter beaucoup plus). La valeur X-FourA-Credits sur la réponse auto correspond à meta.credits dans le corps et suit le coût total de l'escalade.

Pourquoi à la fois un en-tête et un champ dans le corps ?

L'en-tête est pratique : vous pouvez le lire avant d'analyser le corps, le consigner à côté de votre ligne de requête ou l'additionner sur plusieurs appels sans parser le JSON. Le champ meta.credits du corps (Auto) ou les métadonnées par moteur (tableaux de bord Single, Proxy, Browser) contiennent le même nombre, mais accessible directement à l'intérieur de l'enveloppe de réponse.

X-FourA-Limit

X-FourA-Limit apparaît uniquement lorsque l'une des limites de votre forfait a rejeté l'appel. Les rate limits partagés de la plateforme ne le définissent jamais, ce qui fait de cet en-tête le moyen le plus rapide de distinguer "mon forfait a bloqué ceci" de "FourA est occupé" sans analyser le corps de la réponse.

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 renvoient un 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 le résultat.

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 ainsi que les champs du body associés à chacune figurent dans Rate Limits.

X-FourA-Exit-Class

X-FourA-Exit-Class indique la classe de sortie ayant délivré le body : premium pour une sortie premium, standard pour le pool standard. Il apparaît sur une réponse POST /api/proxy/ ayant délivré une page dès lors que la request spécifiait un exitClass, le body portant alors la même valeur, ainsi que sur une réponse Single ou Browser lorsque le proxy que vous avez épinglé était une sortie premium, le body ne comportant aucun champ dédié. Un appel Proxy ayant échoué ne renvoie rien, il ne comporte donc ni le header 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 retourné votre page. Ainsi, une request répondue avec standard a pu consommer du trafic premium lors d'une tentative ayant échoué avant que le pool standard ne réponde. Cet header indique la classe ayant servi la réponse, et non si du trafic premium a été utilisé : le tag premium sur une ligne de l'Activité et la page Usage et limites indiquent ce qui a été décompté. Pour savoir ce que fait exitClass et quand une sortie premium est utilisée : exitClass.

Comportement du cache

L'API ne définit pas Cache-Control ou ETag sur les responses. Chaque appel atteint le backend. Si vous avez besoin de cache, implémentez-le de votre côté.

Headers de réponse de la cible

Les headers retournés par le site cible ne figurent pas sur la response de l'API FourA. Ils sont renvoyés dans l'enveloppe JSON sous le champ headers. Pour les endpoints Single et Proxy, il s'agit d'un tableau d'objets de headers par saut (une entrée par étape de redirection). Pour l'endpoint Browser, il s'agit d'un objet simple contenant les headers de la response 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 à partir du champ headers de l'enveloppe, et non depuis la response HTTP de l'appel API lui-même.

Related

• API Endpoints : Formats des enveloppes de request et de response
• API Errors : Structure des réponses d'erreur
• Request Outcomes : Résultats facturables
• Activity Log : Historique par request indexé par ID de request
• Rate Limits : Signification de chaque valeur X-FourA-Limit