Comment gérer les erreurs de l'API FourA.

Format de réponse d'erreur

L'API renvoie des objets JSON plats pour toutes les erreurs. Il n'y a pas d'objet error imbriqué. Lorsqu'un échec comporte un code lisible par machine, il s'agit d'un champ de premier niveau : reason en cas de limite de forfait, code lors d'un appel proxy sans sortie éligible.

{
  "error": "Invalid API key"
}

Certaines erreurs incluent des champs supplémentaires comme status, service, retryAfter, current ou limits au niveau supérieur :

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

Suivi d'une requête

Chaque réponse d'API (succès ou erreur) comprend un en-tête X-FourA-Request-Id avec un UUID pour cet appel, à l'exception d'un corps que FourA ne peut pas lire du tout (JSON malformé ou corps supérieur à 100 Ko) : il est rejeté avant qu'un identifiant ne soit attribué. Enregistrez-le de votre côté. Si vous devez demander au support ce qui est arrivé à une requête spécifique, cet identifiant nous permet de la retrouver.

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
# Content-Type: application/json
# ...

Types d'erreurs

400: Bad Request

Le corps de la request ne contient pas les champs obligatoires, comporte des valeurs non valides ou indique une cible que l'API refuse de récupérer.

Un corps qui n'est pas un objet ou un tableau JSON constitue un JSON malformé et renvoie Invalid JSON in request body, illustré ci-dessous.

Sur Single, Proxy Finder et Browser, un champ manquant, d'un type incorrect ou hors limites est mentionné dans le message sous la forme <field>: <reason>. Les champs imbriqués sont reliés par des points (validate.status.accept). Jusqu'à cinq problèmes sont listés, séparés par ; , et tout problème supplémentaire termine le message par and <n> more :

{
  "error": "Invalid request: url: Invalid input: expected string, received undefined"
}

Il s'agit d'un client_error et cela n'est pas facturé. Auto signale plutôt un champ qu'il ne peut pas accepter dans un HTTP 200, comme décrit ci-dessous dans la section Lecture des échecs depuis /api/auto/.

Le même code 400 couvre également la protection SSRF. Si votre url résout vers une plage d'adresses IP privée, de bouclage ou réservée (RFC 5735, RFC 6598, blocs réservés IPv6), la request est rejetée avant de quitter le réseau de FourA :

{
  "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."
}

<target> est l'adresse, ou le nom d'hôte et l'adresse obtenue après résolution. Une URL impossible à analyser, ou qui n'est ni http:// ni https://, renvoie la même erreur 400.

Une cible située sur le propre hôte API de FourA (eu.api.foura.ai ou api.foura.ai) reçoit également une erreur 400, sur Single, Proxy Finder, Browser et Auto, avant toute récupération ou facturation. Cela signifie généralement qu'un lien extrait d'une page a été résolu par rapport à l'URL de l'API au lieu de celle de la page elle-même :

{
  "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL."
}

<url> correspond à la cible exactement telle que vous l'avez envoyée. La page Inspect est la seule exception: FourA récupère toujours https://eu.api.foura.ai/inspect pour vous.

Une URL contenant un espace ou un caractère de contrôle reçoit également un code 400, sur Single, Proxy Finder et Auto, avant que quoi que ce soit ne soit récupéré ou facturé. Un lien copié tel quel depuis une page en comporte souvent un (javascript: void(0), un lien de partage contenant des espaces dans son texte). Encodez-le, un espace devenant %20. Browser récupère une telle URL de la même manière que Chrome:

{
  "error": "invalid URL: it contains a space; encode it as %20 (the URL as sent: \"https://example.com/a b\")"
}

Un nom d'hôte impossible à résoudre n'est pas rejeté. L'appel renvoie un code HTTP 200 avec status: 0 ainsi que la raison (could not resolve <host>: <reason>), et il n'est pas facturé. Une cible que FourA tente de joindre sans obtenir de réponse HTTP (limite de redirections atteinte, timeout de connexion ou de lecture, réinitialisation) renvoie également un code HTTP 200, avec error et total_time mais sans status : consultez Request Outcomes.

Sur Single, un corps de réponse dépassant 128 Mo après décodage s'interrompt à cette limite. L'appel renvoie un code HTTP 200 avec "error": "Response body exceeds the 128 MB limit" et n'est pas facturé.

Un JSON malformé dans le corps est rejeté de la même manière, avant la lecture du moindre champ :

{
  "error": "Invalid JSON in request body"
}

Les champs proxy et ignoreProxies ont leurs propres erreurs 400. Tous deux acceptent les identifiants de proxy opaques renvoyés par des réponses précédentes, toute autre valeur échouera donc au décodage :

Message Ce qui s'est passé
Invalid proxy format La valeur de proxy n'est pas un identifiant de proxy émis par FourA. Une adresse proxy brute aboutit ici.
Invalid ignoreProxies format L'une des entrées dans ignoreProxies n'est pas un identifiant de proxy.
Proxy not found L'identifiant a été décodé correctement mais ne correspond plus à une sortie active. Choisissez-en une nouvelle.
Managed exit: this proxy id cannot be pinned to a request La sortie existe, mais FourA ne la maintiendra pas ouverte pour une requête nommée. L'identifiant d'une sortie premium aboutit ici lorsque votre forfait n'a plus de trafic premium disponible. Réutilisez la session qui l'a renvoyé, ou exécutez l'appel via POST /api/proxy/ et utilisez la sortie sélectionnée.

Solution : Vérifiez que votre requête inclut tous les champs obligatoires, que les URL utilisent http:// ou https:// avec chaque espace encodé sous forme de %20, que l'hôte correspond à une adresse publique et que toute valeur de proxy est un identifiant copié textuellement depuis une réponse précédente.

Il s'agit de résultats client_error : la requête n'a jamais quitté FourA, aucune ressource n'a donc été consommée pour votre compte.

401: Unauthorized

Votre clé API est manquante ou invalide.

Clé manquante :

{
  "error": "Missing API key. Include X-API-Key header."
}

Clé non valide :

{
  "error": "Invalid API key"
}

Solution : Vérifiez que votre header X-API-Key contient une clé valide. Générez une nouvelle clé depuis le Dashboard si nécessaire.

Une erreur 401 signifie toujours que FourA a vérifié votre clé et l'a refusée. Lorsque FourA ne peut pas vérifier une clé pendant quelques secondes, il répond par un 503 API key check temporarily unavailable à la place (voir ci-dessous), jamais par un 401.

403: Non inclus dans votre forfait

L'appel a demandé un endpoint ou un paramètre que votre forfait n'inclut pas. La response définit X-FourA-Limit et place le même code dans le body sous reason :

{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

reason est plan_limit_feature pour un endpoint non inclus dans votre forfait ou pour exitCountries et les champs de localisation de sortie sur un forfait sans ciblage géographique, et plan_limit_premium pour exitClass: premium sur un forfait sans sorties premium, ou pour un exit location n'ayant plus de trafic premium disponible. La chaîne error indique l'endpoint ou le paramètre concerné.

Une erreur 403 de FourA ne concerne jamais le site cible : la cible n'a jamais été contactée. Une réponse 403 renvoyée par la cible arrive sous la forme d'un code HTTP 200 avec status: 403 dans le corps.

Solution : Supprimez le paramètre, appelez un endpoint inclus dans votre forfait ou changez d'offre. Aucun en-tête Retry-After n'est défini, car attendre ne changera pas la réponse. Rien n'a été débité : le résultat est rate_limit, et seul success est facturé.

413 : Charge utile trop volumineuse

Le corps de la request JSON dépasse la taille acceptée par FourA (100 Ko). La réponse n'est pas au format JSON et ne contient pas de X-FourA-Request-Id, car le corps est rejeté avant lecture.

Solution : Envoyez une charge utile data plus petite. Rien n'a été débité.

429 : Limite de débit atteinte

Deux vérifications distinctes renvoient un code 429, et elles ne contiennent pas les mêmes champs.

Les limites propres à votre forfait. La response définit un header X-FourA-Limit qui indique la limite ayant rejeté l'appel et place le même code dans le corps sous reason :

{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}

reason est l'un des éléments suivants : plan_limit_concurrency, plan_limit_rate, plan_limit_browser_daily, plan_limit_credits ou plan_limit_bandwidth. Lorsqu'une attente est utile, la durée d'attente se trouve dans retry_after_seconds et dans le header Retry-After, jamais dans retryAfter. plan_limit_browser_daily ne contient ni l'un ni l'autre, car le quota est réinitialisé à minuit UTC et non en secondes. Rien n'a été débité : le résultat est rate_limit, et seul success est facturé.

Le quota partagé de la plateforme. Aucun header X-FourA-Limit, et l'attente se trouve dans retryAfter :

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

current et limits décrivent le service sur l'ensemble du trafic, et non votre compte. Un refus ici signifie que FourA est surchargé.

Correction : Attendez la durée indiquée par Retry-After, retry_after_seconds ou retryAfter selon ce que contient la réponse. En cas de limite de concurrence ou de rate limit, limitez le nombre de requêtes simultanées ouvertes au lieu de renvoyer le lot refusé. En cas de limite journalière ou liée à la période de facturation, arrêtez l'exécution. Consultez Rate Limits pour chaque champ et Run Requests in Parallel pour le modèle à suivre.

500 : Server Error

Une erreur est survenue de notre côté.

Correction : Réessayez la requête après un court délai. Si l'erreur persiste, consultez la page de statut ou contactez le support en fournissant le X-FourA-Request-Id de la réponse en échec.

502 : Upstream Unavailable

FourA n'a pas pu obtenir de réponse de son propre moteur (Upstream unavailable : la connexion a échoué), ou en a reçu une illisible (Malformed JSON from backend).

{
  "error": "Upstream unavailable",
  "details": "..."
}

Solution : Réessayez avec un court délai d'attente (backoff). Le problème vient de notre côté, cela ne vous coûte donc rien : le résultat est service_error et seul success est facturé.

504 : Upstream Timeout

Le moteur n'a pas terminé dans le temps imparti pour cette request.

{
  "error": "Upstream timeout",
  "details": "the backend did not finish inside the time budget for this request"
}

Une erreur 504 concerne la durée d'exécution du traitement, et non votre clé, vos paramètres ou votre proxy. Les cibles lentes, la résolution à froid de challenges et les pages volumineuses en sont les causes habituelles.

Solution : Augmentez timeout_ms sur la request (Single accepte jusqu'à 120000, Browser jusqu'à 120000, Auto jusqu'à 180000), ou réessayez. FourA attend le budget que vous avez déclaré plus une petite marge, donc demander plus de temps vous accorde réellement plus de temps.

503 : Service désactivé ou à pleine capacité

Une erreur 503 signifie soit que le service est temporairement indisponible pour maintenance, soit que la limite de concurrence de la plateforme est atteinte. Les deux formes contiennent les mêmes clés : error, status, service, retryAfter, current et limits. Distinguez-les grâce à la chaîne error, et non selon les champs présents.

{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

Service disabled correspond à une maintenance et current indique 0 pour les deux compteurs, car la requête a été rejetée avant que toute mesure ne soit effectuée. Service at capacity est la variante liée à la concurrence, et dans ce cas current contient l'utilisation réelle de la plateforme. Consultez Rate Limits pour ce format.

Solution : Attendez retryAfter secondes, puis réessayez. La page d'état répertorie les fenêtres de maintenance actives.

Une troisième variante du code 503 ne comporte pas de retryAfter. Elle signifie que le moteur derrière votre endpoint n'a pas pu traiter votre appel : il redémarrait, a échoué du côté de FourA avant l'exécution de votre requête, ou (sur Browser) tous les navigateurs sont restés occupés pendant les 10 secondes d'attente d'une page. backend_status correspond au statut propre du moteur et detail indique le début de sa réponse :

{
  "error": "Backend service unavailable",
  "backend_status": 503,
  "detail": "..."
}

C'est un service_error et ce n'est pas facturé. Réessayez après une seconde ou deux. Une request intrinsèquement incorrecte n'arrive jamais ici : elle reçoit un 400 qui indique le champ concerné.

Un quatrième 503 signifie que FourA n'a pas pu confirmer votre clé API pendant un instant, par exemple lors du basculement de sa base de données. Votre clé n'est pas en cause et rien n'a été exécuté. Elle comporte Retry-After: 5 et la même attente dans retryAfter :

{
  "error": "API key check temporarily unavailable",
  "status": 503,
  "retryAfter": 5
}

Ce n'est pas facturé. Réessayez après retryAfter secondes. Une clé confirmée par FourA au cours des 10 dernières minutes continue de fonctionner pendant un tel événement, cette réponse est donc rare.

Lecture des échecs depuis /api/auto/

POST /api/auto/ répond avec un HTTP 200 chaque fois que l'enchaînement a été exécuté, même si chaque étape a échoué. Le résultat réel se trouve dans le body :

{
  "status": 403,
  "error": "exit blocked by the target defense",
  "attempts": 7,
  "meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}

status est le dernier statut renvoyé par la cible, ou 502 lorsqu'aucune tentative ne l'a atteinte (504 lorsque le budget de temps a été épuisé en premier). Chaque réponse en échec provenant d'une échelle exécutée comporte également un champ attemptReport qui dénombre les erreurs rencontrées par les tentatives, avec un message summary sur une seule ligne qu'il est possible de consigner en toute sécurité dans les logs, tandis que meta.attemptsByEngine et meta.browserRequests indiquent ce que l'appel a envoyé. Consultez Pourquoi un appel Auto a échoué. Un champ de requête non accepté par Auto (par exemple un timeout_ms inférieur à 5000 ou supérieur à 180000) est renvoyé de la même manière: HTTP 200 avec "status": 400 et la raison dans error, avant toute tentative et sans frais.

Ne créez donc pas de branchement conditionnel basé sur le statut de transport pour Auto. Lisez plutôt status et error depuis le corps. Un véritable statut différent de 200 provenant de /api/auto/ signifie que FourA a rejeté l'appel avant le démarrage de l'échelle, ou n'a pas pu le terminer: 400 (JSON mal formé, cible privée ou réservée, ou cible située sur le propre hôte API de FourA), 401, 413, 502, 503 ou 504. Une limite de forfait est gérée dès l'entrée: exitClass: premium sur un forfait sans sorties premium reçoit un 403 avec X-FourA-Limit: plan_limit_premium, avant tout traitement. Toutes les autres limites, les vôtres ou celles de la plateforme, sont renvoyées au sein du 200 avec leur statut dans le corps.

Lorsqu'un site a fait échouer plusieurs appels Auto consécutifs effectués avec votre clé API, Auto répond immédiatement aux appels suivants de cette clé vers ce site pendant un certain temps sans effectuer d'essai: "error": "target temporarily unservable, retry later", "status": 503 et un délai retryAfter en secondes. Cela ne coûte rien; attendez retryAfter secondes.

Une limite de forfait rencontrée par l'un des sous-appels est également renvoyée sous la forme HTTP 200. Le corps contient le refus lui-même, avec son reason, ainsi que status et meta, et la réponse porte le même header X-FourA-Limit qu'un refus direct:

{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}

Les limites qui interrompent la cascade et celles qui ferment uniquement un échelon sont détaillées dans Smart Fetch (Auto).

Échecs côté cible au sein d'un 200 OK

Tous les échecs ne se manifestent pas sous la forme d'un code HTTP non-2xx. Quand la cible répond HTTP 200 mais que la réponse de FourA contient un error (vos règles validate ont rejeté le corps, par exemple) ou que le corps est une page de vérification reconnue par FourA, le résultat est application_error. Quand la cible renvoie un code autre que 200 que vos règles validate n'acceptent pas, le résultat est application_fail et le corps est transmis sans modification.

Aucun de ces cas n'est facturé: seul success l'est. Un appel Browser qui trouve tous les navigateurs occupés attend jusqu'à 10 secondes qu'un navigateur se libère. Si aucun ne se libère, il renvoie le code 503 Backend service unavailable décrit ci-dessus. Browser peut aussi répondre HTTP 200 avec "error": "No available browser slot" lorsqu'il n'a pas pu obtenir de navigateur du tout. Aucun de ces cas n'est facturé. Réessayez après quelques secondes, ou maintenez moins d'appels Browser ouverts simultanément. La documentation de référence Outcomes couvre l'ensemble de la taxonomie.

Un appel Single via un proxy que vous avez épinglé peut également répondre HTTP 200 avec "error": "The exit gave the same answer for <n> different sites" à côté du corps. FourA a constaté que cette sortie transmettait la même page à des sites non liés; la page provient donc de la sortie elle-même, et non de celle que vous avez demandée. Il s'agit de application_error et ce n'est pas facturé. Obtenez une nouvelle sortie depuis POST /api/proxy/, qui écarte automatiquement ce type de sortie.

La même règle s'applique lorsque le réseau propre à la sortie répond à la place du site. L'appel renvoie "error": "The exit answered instead of the site (<name>)" ou "error": "Corporate web gateway intercepted the request (<name>)" (une page de connexion ou de filtrage, ou une redirection vers celle-ci), "error": "The exit intercepted TLS and answered instead of the site (<name>)" lorsque la sortie a répondu à la place du site lui-même, ou "error": "Honeypot echo proxy (plaintext request dump)" lorsque la sortie a renvoyé une copie de votre propre requête. FourA vérifie ces cas quelles que soient vos règles validate, téléchargements returnBuffer compris. Aucun d'entre eux n'est facturé. Obtenez une nouvelle sortie de la même manière.

Encodage des réponses

FourA décode automatiquement les corps de réponse en UTF-8. Si la cible fournit windows-1251, gbk, shift_jis, iso-8859-* ou tout autre jeu de caractères déclaré dans l'en-tête Content-Type ou une balise HTML <meta charset>, vous recevez une chaîne UTF-8 propre dans le champ data (single, proxy) ou body (browser).

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

Stratégie de nouvelle tentative

Une politique pratique de nouvelle tentative:

import time
import requests

# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def make_request(url, payload, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            url,
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json=payload,
        )
        if resp.status_code == 200:
            return resp.json()

        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        request_id = resp.headers.get("X-FourA-Request-Id", "?")

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")

        # Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
        header = resp.headers.get("Retry-After")
        retry_after = (
            int(header) if header and header.isdigit()
            else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
        )

        if resp.status_code in (429, 503):
            time.sleep(retry_after)
            continue
        if resp.status_code >= 500:   # 500, 502, 503, 504 are all ours to fix
            time.sleep(2 ** attempt)
            continue

        # 400/401/403/404 won't fix themselves
        raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")

    raise RuntimeError(f"Exhausted {max_retries} retries")

Les échecs de proxy incluent un rapport

Un appel POST /api/proxy/ qui épuise ses tentatives renvoie un code HTTP 200 avec une enveloppe d'erreur, et non un code d'erreur HTTP. La chaîne d'erreur est courte et a toujours le même format, un objet attemptReport l'accompagne donc avec les décomptes :

{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}

Enregistrez attemptReport.summary à côté de l'erreur et vous saurez si les sorties étaient bloquées, inactives ou si elles renvoyaient des pages rejetées par vos propres règles validate. Référence des champs et mesures à prendre pour chaque compteur : Pourquoi une requête proxy a épuisé ses tentatives.

Mis à jour : 13 novembre 2026