# Problèmes courants

> URL: https://foura.ai/fr/docs/troubleshooting/common-issues
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Solutions aux problèmes les plus fréquents lors de l'utilisation de l'API FourA.

## Contenu vide ou incomplet

**Symptôme :** l'API renvoie un statut 200 mais le champ `data` est vide ou ne contient pas les données attendues.

**Cause :** la page cible utilise JavaScript pour afficher le contenu après le chargement initial.

**Solution :** passez de l'endpoint unique à l'endpoint browser. Utilisez `checkText` pour vérifier que le contenu est bien chargé :

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Remarque : le endpoint browser renvoie le contenu dans le champ `body` (et non `data`).

## Pages 403 Forbidden ou de vérification

**Symptôme :** L'API renvoie du HTML contenant une page de vérification ou une page d'accès refusé.

**Cause :** Le site cible a détecté que la request était automatisée et l'a bloquée.

**Solution :** Utilisez le endpoint proxy pour bénéficier de la rotation automatique d'IP :

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'
```

Si le problème persiste, augmentez `maxTries` pour accorder davantage de tentatives à la rotation des proxy.

Une erreur 403 renvoyée par la cible arrive sous la forme d'un code HTTP 200 avec `status: 403` dans le corps de la réponse. Une erreur 403 sur l'appel lui-même, accompagnée d'un header `X-FourA-Limit`, correspond à un cas différent : consultez [403 Not in Your Plan](#403-not-in-your-plan).

## Erreurs de timeout

**Symptôme :** Les requêtes échouent avec une erreur de timeout.

**Cause :** La page cible met plus de temps à charger que le timeout configuré.

**Solution :** Augmentez `timeout_ms` (la valeur par défaut est de 15 s pour single, 30 s pour browser, 45 s pour proxy) :

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'
```

Pour les requêtes de navigateur, vérifiez également que votre valeur `checkText` apparaît bien sur la page. Une faute de frappe fait échouer l'appel avec `checkText:<your text> not found`.

## 403 Non inclus dans votre forfait

**Symptôme :** L'API renvoie 403 avec un header `X-FourA-Limit` et un `reason` valant `plan_limit_feature` ou `plan_limit_premium`.

```json
{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

**Cause :** Votre forfait n'inclut pas l'endpoint appelé ou le paramètre envoyé. `plan_limit_feature` couvre un endpoint exclu, ainsi que `exitCountries`, `exitState`, `exitCity`, `exitAsn` ou `exitOs` sans ciblage géographique. `plan_limit_premium` couvre `exitClass: premium` sans sorties premium, ainsi qu'une requête Proxy spécifiant un [emplacement de sortie](https://foura.ai/docs/api/endpoints#exit-location) une fois votre trafic premium épuisé. La cible n'a jamais été contactée et rien n'a été débité.

**Solution :** Supprimez le paramètre, appelez un endpoint inclus dans votre forfait, ou passez à une offre supérieure. L'onglet **Limites et fonctionnalités** de [Utilisation et limites](https://foura.ai/docs/dashboard/quota) détaille le contenu de votre forfait. Ne réessayez pas à l'identique : aucun `Retry-After` n'est défini car attendre ne changera pas le résultat.

## 429 Trop de requêtes

**Symptôme :** L'API renvoie 429.

**Cause :** L'une des deux vérifications a rejeté l'appel, et la réponse indique laquelle. Si elle contient un header `X-FourA-Limit`, l'une des limites de votre forfait a été atteinte : requêtes simultanées ou requêtes par minute sur cet endpoint, requêtes Browser pour la journée, ou crédits ou bande passante pour la période de facturation. En l'absence d'un tel header, le quota partagé par minute de la plateforme pour ce service était saturé, ce qui concerne le trafic global de FourA et non le vôtre.

**Solution :** Lisez d'abord `X-FourA-Limit`. Patientez lorsque la limite se réinitialise en quelques secondes, et arrêtez dans le cas contraire. Les limites de forfait qu'une attente permet de réinitialiser indiquent les secondes dans le header `Retry-After` et dans `retry_after_seconds` ; la limite partagée les indique dans `retryAfter` :

```python
import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)
```

Si l'en-tête indiquait `plan_limit_concurrency` ou `plan_limit_rate`, la solution consiste à limiter le nombre d'appels simultanés ouverts ainsi que le nombre d'appels lancés par minute plutôt que de réessayer plus agressivement. Renvoyer immédiatement un lot refusé entraîne le rejet systématique de l'ensemble du lot. Les appels refusés ne sont pas décomptés de votre limite par minute, mais s'ils continuent d'arriver à plus du double de cette limite, les refus se transforment en période de temporisation: le corps de la réponse 429 contient `cooldown: true` et vous demande de faire une pause de 30 secondes (`retry_after_seconds: 30`). [Exécuter des requêtes en parallèle](https://foura.ai/docs/how-to/run-requests-in-parallel) détaille ce modèle, et la section **Usage & Limites** du [Tableau de bord](https://foura.ai/dashboard) affiche vos compteurs en direct en regard de vos plafonds.

## 503 Service indisponible

**Symptôme:** L'API renvoie un statut 503.

**Cause:** Cette situation se produit dans trois cas:

1. **Le service est à pleine capacité.** FourA exécute déjà autant de requêtes sur ce moteur qu'il n'est autorisé à en traiter simultanément, calculé sur l'ensemble du trafic global et non uniquement sur le vôtre. `Service at capacity` apparaît dans le champ `error`. La situation se résout généralement en quelques secondes.
2. **Service temporairement désactivé.** Une opération de maintenance est en cours. `Service disabled` apparaît dans le champ `error`.
3. **FourA ne peut momentanément pas vérifier votre clé.** `API key check temporarily unavailable` apparaît dans le champ `error`, accompagné de `Retry-After: 5`. Votre clé est valide.

Ces trois cas renvoient tous un champ `retryAfter` dans la réponse. Aucun d'eux ne correspond à une limite de forfait: les limites de votre propre forfait déclenchent toujours un en-tête `X-FourA-Limit` sur une erreur 403 ou 429, jamais avec une 503.

**Solution:** Attendez `retryAfter` secondes, puis réessayez:

```python
import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")
```

Une erreur 503 indique que FourA est saturé. La seule solution consiste à temporiser puis à réessayer. Si vous recevez plutôt un refus 429 avec `X-FourA-Limit`, le problème vient de votre côté : réduisez le nombre de requêtes parallèles dans votre pipeline.

## 504 Expiration du délai en amont

**Symptôme :** L'API renvoie 504 avec `{"error": "Upstream timeout"}`.

**Cause :** L'opération ne s'est pas terminée dans le temps imparti que vous avez défini pour la requête. Une cible lente, la résolution à froid d'un challenge ou une page très volumineuse peuvent en être l'origine. Il ne s'agit pas d'un problème lié à votre clé, à vos paramètres ou à votre proxy.

**Solution :** Accordez plus de temps à l'appel, ou réessayez. FourA attend la valeur de votre `timeout_ms` plus une légère marge, donc l'augmenter prolonge réellement l'attente :

```json
{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}
```

Pour `/api/auto/` sur une cible protégée, un premier appel à froid peut prendre plusieurs dizaines de secondes. Son `timeout_ms` couvre l'ensemble de la séquence et accepte jusqu'à 180000.

Lorsque `/api/auto/` épuise lui-même ce budget, l'appel renvoie tout de même un code HTTP 200. Le corps contient un `error` qui commence par `time budget exhausted`, et `status` est généralement 504 (une tentative précédente ayant échoué peut laisser son propre statut à la place). Augmentez `timeout_ms` ou réessayez.

## 502 Upstream Indisponible

**Symptôme :** L'API renvoie 502 avec `{"error": "Upstream unavailable"}`, ou 503 avec `{"error": "Backend service unavailable"}`.

**Cause :** FourA n'a pas pu joindre son propre moteur (`Upstream unavailable`), ou le moteur n'a pas renvoyé de réponse exploitable (`Backend service unavailable`), généralement parce qu'une instance redémarrait. Sur `/api/browser/`, une page attend jusqu'à 10 secondes qu'un navigateur se libère lorsque tous sont occupés, et une page qui attend toujours après ce délai renvoie cette erreur 503.

**Solution :** Réessayez avec un court délai d'attente (backoff). Les deux sont classés comme `service_error`, et seul `success` est facturé, une nouvelle tentative ne vous coûte donc rien de plus. Si le problème persiste plus d'une minute ou deux, consultez la [page de statut](https://updates.foura.ai/status).

## Erreurs d'authentification 401

**Symptôme :** Chaque requête renvoie 401 Unauthorized.

**Liste de contrôle :**
1. Vérifiez que l'en-tête est bien `X-API-Key: YOUR_API_KEY` (et non `Authorization: Bearer` ou `Api-Key`)
2. Vérifiez l'absence d'espaces supplémentaires ou de sauts de ligne dans votre clé d'API
3. Créez une nouvelle clé depuis le [Dashboard](https://foura.ai/dashboard) si la clé actuelle est potentiellement compromise

## 400 Requête non valide

**Symptôme :** Un appel à `POST /api/single/`, `/api/proxy/` ou `/api/browser/` renvoie 400 avec `{"error": "Invalid request: <field>: <reason>; ..."}`.

**Cause :** Un champ de votre corps de requête est manquant, a un type incorrect ou dépasse les limites autorisées. Le message indique chaque champ non accepté et la raison associée, jusqu'à cinq champs, suivis de `and N more` s'il en existe d'autres. Rien n'a été récupéré, le résultat est `client_error` et aucun crédit n'est consommé.

**Solution :** Corrigez les champs indiqués et renvoyez la requête. Le même corps de requête produira la même erreur 400, ne réessayez donc pas sans modification. La [référence des endpoints](https://foura.ai/docs/api/endpoints) liste chaque champ avec son type et ses limites. Sur `/api/auto/`, la même erreur renvoie un code HTTP 200 avec `status: 400` et la raison dans `error`.

## 400 La cible résout vers une IP privée ou réservée

**Symptôme :** L'API renvoie 400 avec `Refusing to fetch <target>: target resolves to a private or reserved IP range` avant même que la requête ne quitte FourA.

**Cause :** Votre `url` résout vers une plage d'adresses IP privée, de bouclage ou réservée (RFC 5735, RFC 6598 ou blocs réservés IPv6). FourA refuse ces cibles afin que son réseau ne puisse pas être utilisé pour accéder à des hôtes internes.

**Solution :** Récupérez une URL publique. Si vous effectuez des tests, utilisez une cible publique comme `https://example.com` ou `https://httpbin.org/get`. Si votre cible prévue est un service que vous gérez, exposez-le d'abord sur un nom d'hôte public.

```json
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
```

Un nom d'hôte impossible à résoudre n'est pas rejeté. L'appel renvoie HTTP 200 avec `status: 0` et la raison (`could not resolve <host>: <reason>`), comme toute cible que FourA ne peut pas joindre, et il n'est pas facturé.

## 400 Espace dans l'URL

**Symptôme :** Single, Proxy ou Auto renvoie 400 avec `invalid URL: it contains a space; encode it as %20 (the URL as sent: "...")` avant que la requête ne quitte FourA.

**Cause :** L'URL contient un espace ou un caractère de contrôle, généralement issu d'un lien extrait tel quel d'une page (`javascript: void(0)`, un lien de partage contenant du texte). Rien n'est récupéré, le résultat est `client_error`, et aucun crédit n'est débité.

**Solution :** Encodez l'URL avant de l'envoyer (un espace devient `%20`), et ignorez les liens qui ne sont pas des pages, comme ceux de type `javascript:`. Browser récupère une telle URL de la même manière que Chrome.

## 400 La cible est l'API FourA elle-même

**Symptôme :** L'API renvoie 400 avec `Refusing to fetch <url>: that is the FourA API itself, not a page.` avant que la requête ne quitte FourA.

**Cause :** Votre `url` pointe vers `api.foura.ai` ou `eu.api.foura.ai`. Un crawler produit généralement ce comportement lorsqu'il résout un lien relatif d'une page par rapport à l'URL de l'API au lieu de l'URL propre à la page, transformant ainsi `/category/news/` en `https://eu.api.foura.ai/category/news/`. Rien n'est récupéré et aucun crédit n'est débité.

**Solution :** Résolvez chaque lien par rapport à l'URL de sa page d'origine avant de l'envoyer, par exemple avec `urljoin(page_url, href)` en Python. L'[endpoint Inspect](https://foura.ai/docs/api/inspect) (`/inspect`) est la seule adresse sur l'hôte de l'API que vous pouvez interroger via FourA.

## no_eligible_proxy lors de l'utilisation d'exitCountries

**Symptôme :** Un appel `/api/proxy/` avec `exitCountries` renvoie HTTP 200 avec une enveloppe d'erreur JSON :

```json
{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}
```

**Cause :** Le pool de proxy actuel ne dispose d'aucune sortie fonctionnelle dont le pays visible par la cible correspond à votre liste verte. Le pool standard ne bascule jamais vers un pays non demandé lorsque vous définissez `exitCountries`. Sans `exitCountries`, la même situation renvoie `{"error": "Failed"}` : FourA n'avait aucune sortie à essayer, réessayez donc après quelques secondes.

Une request qui spécifie un emplacement de sortie (`exitState`, `exitCity`, `exitAsn`, `exitOs` ou `exitLifetimeMin`, avec `exitClass: premium`) passe exclusivement par des sorties premium. Lorsque FourA n'a plus aucune sortie premium à tester pour celle-ci, l'appel se termine avec `"error": "No premium exit answered for this request"` et le même `code: no_eligible_proxy`.

**Solution :** Conservez le périmètre demandé et réessayez plus tard. Le pool est actualisé environ toutes les dix minutes, de sorte qu'un pays sans correspondance actuelle en obtient souvent une dans l'heure.

```python
import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")
```

Élargissez la liste des pays uniquement si les exigences géographiques de votre workflow ont réellement changé. Les solutions de repli silencieuses vers d'autres pays peuvent casser la logique dépendante de la géolocalisation en aval.

## Un profil de navigateur est refusé

**Symptôme :** L'appel renvoie `unknown profile '<id>'`, `no profile matches browser=...` ou `browser profile selection requires unblocker:true`.

**Cause :** La valeur `profile`, `browser`, `os` ou `version` envoyée ne figure pas dans le catalogue, ou vous en avez envoyé une avec `unblocker: false`.

**Solution :** Consultez [`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles) pour obtenir le catalogue actuel, faites votre choix dans celui-ci et gardez `unblocker` activé lorsque vous choisissez un navigateur.

## Le corps de la réponse contient du texte illisible

**Symptôme :** Le champ `data` (ou `body`) de la réponse contient du mojibake ou des caractères illisibles lorsque la cible utilise un encodage non-UTF-8.

**Cause :** Par défaut, FourA décode automatiquement les corps de réponse en UTF-8 selon l'en-tête `Content-Type` de la cible ou une balise HTML `<meta charset>`. Si la cible indique un encodage erroné, vous obtenez du texte déformé.

**Solution :** Pour les charges utiles binaires (images, protobuf, audio brut), définissez `returnBuffer: true` sur la requête. Single et Proxy renvoient alors `data` sous la forme d'un objet contenant les octets bruts, `{"type": "Buffer", "data": [<byte values>]}`, sans aucun transcodage de jeu de caractères appliqué.

```json
{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}
```

Pour les cibles texte qui déclarent incorrectement leur jeu de caractères, décodez vous-même les octets bruts : effectuez la requête avec `returnBuffer: true`, lisez les valeurs d'octets dans `data.data`, puis décodez-les avec le bon jeu de caractères.

## HTML inattendu au lieu de JSON

**Symptôme :** Vous attendiez du JSON du site cible mais vous avez reçu du HTML.

**Cause :** La page cible peut renvoyer un contenu différent selon les en-têtes.

**Solution :** Ajoutez un en-tête `Accept` et activez `unblocker` pour obtenir des en-têtes de navigateur réalistes :

```bash
curl -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://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'
```

Vous pouvez aussi définir `tryJsonData` sur `true` pour que FourA analyse automatiquement les réponses JSON.

## Le corps de la réponse est une page de challenge, pas le contenu attendu

**Symptôme :** L'appel a réussi, `status` renvoie 200, mais `data` (ou `body`) correspond à une vérification anti-bot au lieu de la page souhaitée.

**Cause :** La cible a déclenché une vérification anti-bot que FourA a rencontrée sans pouvoir la résoudre. La réponse l'indique : Single et Proxy renvoient `defense` avec `solved: false`, et Browser renvoie `defenseSolved: false` avec le fournisseur dans `defenses.present`.

**Solution :** Vérifiez d'abord `defense.vendor`, puis appliquez un niveau supérieur. Essayez un autre profil de navigateur sur Single, passez à Proxy pour changer d'IP de sortie, ou utilisez Browser pour exécuter le JavaScript. Référence complète des champs et liste des fournisseurs : [Site checks](https://foura.ai/docs/api/site-checks).

Ajoutez une sous-chaîne `validate.data.accept` présente uniquement sur la vraie page. Une page de vérification reconnue par FourA n'est jamais considérée comme un succès : elle est renvoyée avec un header `X-FourA-Check-Page` et n'est pas facturée. Sans `validate`, une page de vérification non reconnue par FourA, renvoyée avec un code HTTP 200, est comptabilisée comme un succès, et vous ne le détectez qu'en aval au lieu du moment de l'appel.

## Toujours bloqué ?

Si aucune des solutions ci-dessus ne fonctionne :

1. Consultez la [page de statut](https://updates.foura.ai/status) pour repérer d'éventuels incidents en cours
2. Examinez les métriques de vos requêtes dans le [Dashboard](https://foura.ai/dashboard)
3. Contactez le support à support@foura.ai avec les détails de votre requête (incluez le `X-FourA-Request-Id` de la réponse en échec)

## Étapes suivantes

- [Error Handling](https://foura.ai/docs/api/errors) : référence des codes d'erreur de l'API
- [Rate Limits](https://foura.ai/docs/api/rate-limits) : toutes les limites de forfait et de plateforme, avec les champs associés
- [Request Outcomes](https://foura.ai/docs/api/outcomes) : comment les résultats catégorisent ce qui s'est produit
- [Site checks](https://foura.ai/docs/api/site-checks) : ce que le champ `defense` vous indique
- [Choosing the Right Endpoint](https://foura.ai/docs/guides/choosing-task-type) : choisissez la méthode la plus adaptée à votre cible
- [Dashboard Overview](https://foura.ai/docs/dashboard/overview) : surveillez vos requêtes
