# Headers de réponse

> URL: https://foura.ai/fr/docs/api/response-headers
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

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](https://foura.ai/docs/api/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.

```bash
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é](https://foura.ai/docs/dashboard/activity-log) 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é

```python
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()
```

```javascript
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](https://foura.ai/docs/api/outcomes) 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é](https://foura.ai/docs/dashboard/activity-log) 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.

```python
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](https://foura.ai/docs/api/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é](https://foura.ai/docs/dashboard/activity-log) et la page [Utilisation et limites](https://foura.ai/docs/dashboard/quota) indiquent ce qui a été comptabilisé. Pour comprendre le fonctionnement de `exitClass` et savoir quand une sortie premium est utilisée : [exitClass](https://foura.ai/docs/api/endpoints#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](https://foura.ai/docs/dashboard/quota), 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](https://foura.ai/docs/api/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](https://foura.ai/docs/guides/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.

```json
{
  "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.

## Liens associés

- [Endpoints API](https://foura.ai/docs/api/endpoints): Formats des enveloppes de request et de response
- [Erreurs API](https://foura.ai/docs/api/errors): Structure des responses d'erreur
- [Résultats des requests](https://foura.ai/docs/api/outcomes): Résultats facturables
- [Journal d'activité](https://foura.ai/docs/dashboard/activity-log): Historique par request indexé par ID de request
- [Rate Limits](https://foura.ai/docs/api/rate-limits): Signification de chaque valeur `X-FourA-Limit`
