Problèmes courants
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é :
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 :
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.
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) :
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.
{
"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 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 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 :
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 détaille ce modèle, et la section Usage & Limites du Tableau de bord 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:
- 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 capacityapparaît dans le champerror. La situation se résout généralement en quelques secondes. - Service temporairement désactivé. Une opération de maintenance est en cours.
Service disabledapparaît dans le champerror. - FourA ne peut momentanément pas vérifier votre clé.
API key check temporarily unavailableapparaît dans le champerror, accompagné deRetry-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:
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 :
{
"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.
Erreurs d'authentification 401
Symptôme : Chaque requête renvoie 401 Unauthorized.
Liste de contrôle :
- Vérifiez que l'en-tête est bien
X-API-Key: YOUR_API_KEY(et nonAuthorization: BearerouApi-Key) - Vérifiez l'absence d'espaces supplémentaires ou de sauts de ligne dans votre clé d'API
- Créez une nouvelle clé depuis le 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 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.
{ "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 (/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 :
{
"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.
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 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é.
{
"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 :
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.
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 :
- Consultez la page de statut pour repérer d'éventuels incidents en cours
- Examinez les métriques de vos requêtes dans le Dashboard
- Contactez le support à support@foura.ai avec les détails de votre requête (incluez le
X-FourA-Request-Idde la réponse en échec)
Étapes suivantes
- Error Handling : référence des codes d'erreur de l'API
- Rate Limits : toutes les limites de forfait et de plateforme, avec les champs associés
- Request Outcomes : comment les résultats catégorisent ce qui s'est produit
- Site checks : ce que le champ
defensevous indique - Choosing the Right Endpoint : choisissez la méthode la plus adaptée à votre cible
- Dashboard Overview : surveillez vos requêtes