Rate limits
Chaque requête API FourA passe par trois vérifications avant d'atteindre un moteur : les limites de votre propre forfait, puis l'allocation partagée de la plateforme pour l'ensemble du trafic, puis l'allocation partagée de la plateforme pour l'endpoint appelé. Chaque vérification peut refuser une requête de manière indépendante, et chacune renvoie un corps de réponse distinct.
Les trois vérifications, dans l'ordre
- Limites du forfait. Ce que votre propre forfait autorise : les endpoints et paramètres inclus, le nombre de requêtes simultanées autorisées par endpoint, le nombre par minute, le nombre de requêtes de navigateur par jour, ainsi que les crédits et la bande passante disponibles sur la période de facturation.
- Limite globale de la plateforme. Tout ce que l'hôte API appelé traite à cet instant, quel que soit l'endpoint ciblé par le trafic. Un refus à ce niveau renvoie
"service": "api". - Limite de la plateforme par endpoint. Le trafic sur le service single, proxy ou browser appelé.
Votre propre forfait est évalué en premier, et cet ordre constitue le contrat plutôt qu'un détail d'implémentation. Les allocations partagées étant une ressource commune, une requête que la plateforme allait de toute façon refuser ne doit pas les consommer avant d'être rejetée. Un compte envoyant bien plus que ce que son forfait autorise est interrompu avant de toucher à ce que les autres utilisent.
Les vérifications 2 et 3 comptabilisent le trafic total de FourA, pas le vôtre. Interprétez un refus de l'une d'elles comme "FourA est occupé", et non comme "vous avez envoyé trop de requêtes". La vérification 1 concerne uniquement votre compte, et aucun autre élément sur la plateforme ne l'impacte.
Un refus provenant de l'une des vérifications partagées restitue à votre compte tout ce que son admission avait comptabilisé, le quota par minute comme le créneau journalier de navigateur, car la requête n'a jamais atteint de backend. Elle ne compte pas non plus pour la pause de nouvelle tentative décrite sous Requêtes par minute : c'est la capacité de FourA qui l'a refusée, pas votre forfait.
POST /api/auto/ ne réserve aucun créneau propre. Les sous-appels Single, Proxy et Browser qu'il effectue pour vous passent les trois vérifications comme n'importe quelle autre requête, de sorte qu'un lot parallèle d'appels auto est décompté de votre forfait par l'intermédiaire de ses sous-appels. (Vos totaux de requêtes et votre taux de réussite comptabilisent l'appel auto lui-même, une seule fois ; les sous-appels apparaissent comme ses tentatives.)
Limites du forfait
Une limite de forfait répond avec un header X-FourA-Limit indiquant quelle limite a refusé l'appel. Le même code se trouve dans le corps sous reason, ce qui vous permet de conditionner votre logique sans lire les headers. Chaque corps de réponse lié à une limite de forfait contient error, reason et documentation ; le reste des champs dépend de la limite.
X-FourA-Limit |
Statut | Limite atteinte |
|---|---|---|
plan_limit_feature |
403 | L'endpoint appelé, ou le paramètre exitCountries, exitState, exitCity, exitAsn ou exitOs, n'est pas inclus dans votre forfait |
plan_limit_premium |
403 | exitClass: premium n'est pas inclus dans votre forfait, ou une requête Proxy spécifie un emplacement de sortie sans trafic premium restant |
plan_limit_concurrency |
429 | Requêtes simultanées sur cet endpoint |
plan_limit_rate |
429 | Requêtes par minute sur cet endpoint |
plan_limit_browser_daily |
429 | Requêtes de navigateur pour la journée |
plan_limit_credits |
429 | Crédits facturés pour la période de facturation |
plan_limit_bandwidth |
429 | Bande passante pour la période de facturation |
Les chiffres associés à chaque limite dépendent de votre forfait, et l'onglet Limites et fonctionnalités de Utilisation et limites les affiche à côté de votre utilisation en direct. Ne les écrivez pas en dur dans votre code : chaque refus indique le plafond qui l'a déclenché.
Une requête refusée ne consomme rien. Le résultat est rate_limit, et seul success est facturé.
Endpoint ou paramètre non inclus dans le forfait
Un code 403 avec plan_limit_feature signifie que l'appel a demandé un élément qui n'est pas inclus dans votre forfait. La vérification s'exécute avant tout décompte, de sorte que l'appel refusé n'affecte ni vos compteurs de débit ni vos compteurs journaliers.
{
"error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
Le même code et le même statut répondent à un appel POST /api/proxy/ qui définit exitCountries, exitState, exitCity, exitAsn ou exitOs sur un forfait sans ciblage géographique. La chaîne error indique le paramètre :
{
"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"
}
plan_limit_premium a le même format pour exitClass: premium sur un forfait sans sorties premium. Un forfait qui inclut des sorties premium mais a épuisé le trafic premium de cette période n'est pas refusé, sauf si une request Proxy spécifie un emplacement de sortie : la request est servie depuis le pool standard et la response indique exitClass: standard. Aucun de ces cas ne consomme de sortie premium. Consultez exitClass.
Aucun code 403 ne définit Retry-After. Attendre ne changera pas le résultat.
Requêtes simultanées
La concurrence est comptabilisée par endpoint : votre forfait applique un plafond pour Single, un pour Proxy et un pour Browser. La request qui dépasse la limite renvoie un code 429 avec Retry-After: 1 :
{
"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
}
in_flight comptabilise également la requête refusée, sa valeur est donc supérieure d'au moins une unité à limit.
La solution consiste à limiter votre propre parallélisme plutôt qu'à multiplier les tentatives. Répondre à un code 429 en renvoyant immédiatement le même lot génère un autre 429 pour chaque appel qu'il contient. Consultez Exécuter des requêtes en parallèle pour un modèle fonctionnel.
Requêtes par minute
Single et Proxy disposent d'un quota par minute, mesuré sur une minute glissante. Seules les requêtes acceptées sont comptabilisées: une requête refusée est déduite, de sorte qu'un compte effectuant régulièrement des demandes légèrement supérieures à son quota se voit servir son quota au lieu de voir la quasi-totalité de ses requêtes refusées.
{
"error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 613,
"retry_after_seconds": 17
}
retry_after_seconds correspond à la durée d'attente avant qu'une nouvelle request ne soit acceptée, si vous n'envoyez rien d'autre entre-temps : au moins 1 seconde et au plus 120. Le header Retry-After transmet la même valeur.
Réessayer des requests refusées plus rapidement que ce délai suit une règle spécifique. Lorsque les requests refusées par cette limite au cours de la minute glissante dépassent le double de la limite autorisée, l'appel est rejeté avec une pause imposée de 30 secondes :
{
"error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 540,
"refused_last_minute": 1250,
"cooldown": true,
"retry_after_seconds": 30
}
Les refus survenus pendant la pause ne sont pas comptabilisés. La pause se termine donc d'elle-même au fil de la minute, même pour un client qui continue à réessayer. Pour distinguer la pause du quota ordinaire, lisez cooldown plutôt que le texte de error.
Requêtes Browser par jour
Browser n'a pas de quota par minute. La limite de son forfait est un nombre de requêtes Browser par jour, comptabilisées à partir de minuit UTC, et le compteur prend en compte chaque requête Browser acceptée, pas seulement celles qui réussissent. Un appel Browser qui échoue du côté de FourA à zéro crédit, comme le 503 Backend service unavailable, libère son créneau quotidien. Les réponses Browser et Auto non refusées par vos limites incluent le compteur et la limite dans les headers X-FourA-Browser-Used-Today et X-FourA-Browser-Limit-Per-Day : voir Headers de réponse.
{
"error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
"reason": "plan_limit_browser_daily",
"documentation": "https://foura.ai/prices",
"limit_per_day": 300,
"used_today": 301
}
Ce refus ne comporte aucun header retry_after_seconds ni Retry-After, car l'attente se compte en heures et non en secondes. Considérez-le comme un arrêt et planifiez la prochaine exécution pour minuit UTC.
Crédits pour la période de facturation
Seuls les crédits facturés sont pris en compte, c'est-à-dire uniquement les requêtes réussies. Lorsque le total facturé atteint les crédits dont vous disposez pour cette période, les requêtes suivantes sont refusées jusqu'à la réinitialisation de la période ou jusqu'à ce que vous en achetiez davantage.
{
"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"
}
hard_stop correspond au nombre de crédits facturés à partir duquel les requêtes s'arrêtent pour cette période. Lisez-le directement depuis le corps plutôt que de le calculer: il inclut déjà tous les crédits achetés en plus du forfait.
Bande passante pour la période de facturation
Les forfaits avec une limite de bande passante refusent les requêtes dès que le trafic standard de cette période l'atteint. Le trafic Premium dispose de son propre quota et n'est pas décompté de cette limite. La bande passante achetée est traitée de la même façon que la bande passante incluse, et la chaîne error indique ce qui est à votre disposition, et non ce que le forfait seul comprend.
{
"error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
"reason": "plan_limit_bandwidth",
"documentation": "https://foura.ai/prices",
"used_bytes": 53687091200,
"limit_bytes": 53687091200,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z"
}
Sur les deux limites de période, retry_after_seconds est plafonné à 24 heures ; resets_at est l'instant exact où la période se renouvelle.
Champs des limites de forfait
| Champ | Type | Présent sur | Description |
|---|---|---|---|
error |
string | tous | Message lisible par l'humain, incluant la valeur limite qui vous est appliquée |
reason |
string | tous | plan_limit_ suivi du nom de la limite. Même valeur que l'en-tête X-FourA-Limit. |
documentation |
string | tous | Lien vers la page des forfaits |
retry_after_seconds |
number | simultanéité, taux, crédits, bande passante | Temps d'attente requis. Même valeur que l'en-tête Retry-After. |
limit |
number | simultanéité | Requêtes simultanées autorisées par le forfait sur cet endpoint |
in_flight |
number | simultanéité | Requêtes en cours d'exécution sur cet endpoint pour votre compte, incluant celle refusée |
limit_per_minute |
number | taux | Requêtes par minute autorisées par le forfait sur cet endpoint |
current_rate |
number | taux | Requêtes comptabilisées sur la minute glissante, incluant celle refusée |
refused_last_minute |
number | pause de taux | Requêtes rejetées par le quota par minute sur la minute glissante. Uniquement lors de la pause de 30 secondes. |
cooldown |
boolean | pause de taux | true lors de la pause de 30 secondes pour nouvelle tentative trop rapide. Absent lors d'un refus classique par minute. |
limit_per_day |
number | navigateur par jour | Requêtes de navigateur autorisées par le forfait par jour |
used_today |
number | navigateur par jour | Requêtes de navigateur comptabilisées aujourd'hui, incluant celle refusée |
used |
number | crédits | Crédits facturés jusqu'à présent sur cette période |
hard_stop |
number | crédits | Seuil de crédits facturés à partir duquel les requêtes sont bloquées sur cette période |
used_bytes |
number | bande passante | Trafic standard consommé jusqu'à présent sur cette période, en octets. Le trafic premium n'est pas inclus. |
limit_bytes |
number | bande passante | Octets disponibles sur cette période |
resets_at |
string | crédits, bande passante | Horodatage ISO 8601 de la fin de la période |
Les limites de forfait utilisent retry_after_seconds. Les limites de plateforme ci-dessous utilisent retryAfter. Un gestionnaire de nouvelles tentatives doit lire les deux, ou lire l'en-tête Retry-After, que les limites de forfait définissent, tout comme l'erreur 503 API key check temporarily unavailable (voir Errors).
Limites de plateforme
Les vérifications de la plateforme surveillent deux métriques par service et une supplémentaire pour l'ensemble des services :
- Simultanéité : nombre de requêtes que FourA exécute en parallèle.
- RPM : nombre de requêtes traitées par FourA au cours des 60 dernières secondes.
Les deux compteurs sont partagés entre tous les utilisateurs de ce service. current et limits dans les réponses ci-dessous décrivent la plateforme, pas votre compte. Si vous souhaitez connaître vos propres chiffres, lisez in_flight dans une réponse de limite de forfait, ou ouvrez Usage & Limits dans le dashboard.
429: RPM dépassé
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": {
"concurrency": 12,
"rpm": 3000
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
Le service a atteint son quota de requêtes autorisées pour la dernière minute. Attendez retryAfter secondes.
503 : Concurrence dépassée
{
"error": "Service at capacity",
"status": 503,
"service": "proxy",
"retryAfter": 2,
"current": {
"concurrency": 500,
"rpm": 1200
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
Le service traite actuellement autant de requêtes qu'il est autorisé à en exécuter simultanément. Cela se résout en quelques secondes.
Service désactivé
Lorsqu'un service est temporairement mis hors ligne pour maintenance, l'API renvoie une erreur 503 avec un message d'erreur différent :
{
"error": "Service disabled",
"status": 503,
"service": "single",
"retryAfter": 60,
"current": { "concurrency": 0, "rpm": 0 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
Ceci n'est pas un rate limit. Le service est temporairement indisponible. Verifiez la valeur de retryAfter et reessayez apres ce nombre de secondes. Cela se resout generalement en quelques minutes.
Les deux formats de 503 comportent les memes cles, effectuez donc votre branchement conditionnel sur la chaine error et jamais sur les champs presents. Service disabled correspond a la maintenance, Service at capacity a la concurrence.
Sur le format de maintenance, current.concurrency et current.rpm valent toujours 0 : la request a ete rejetee avant toute mesure.
Champs des limites de la plateforme
| Champ | Type | Description |
|---|---|---|
error |
string | Message d'erreur lisible par l'humain |
status |
number | Code de statut HTTP (429 ou 503) |
service |
string | Service ayant refuse l'appel : single, proxy, browser ou api |
retryAfter |
number | Temps d'attente recommande en secondes avant de reessayer |
current.concurrency |
number | Requests en cours d'execution sur le service pour l'ensemble des clients lors du refus |
current.rpm |
number | Requests traitees par le service pour l'ensemble des clients au cours des 60 dernieres secondes |
limits.maxConcurrency |
number | Limite de concurrence partagee du service |
limits.maxRpm |
number | Limite partagee par minute du service |
Gerer chaque refus avec une seule fonction helper
Retry-After est defini sur les limites de forfait pour lesquelles l'attente est utile, retry_after_seconds se trouve dans leur corps, et retryAfter se trouve dans les corps de la plateforme. Lisez les trois dans cet ordre, et interrompez le traitement pour les limites de forfait qu'aucune attente ne debloquera :
import time
import requests
# Plan limits that a short wait never clears.
STOP_ON = {
"plan_limit_feature",
"plan_limit_premium",
"plan_limit_browser_daily",
"plan_limit_credits",
"plan_limit_bandwidth",
}
def wait_seconds(resp, attempt):
header = resp.headers.get("Retry-After")
if header and header.isdigit():
return int(header)
try:
body = resp.json()
except ValueError:
return 2 ** attempt
return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
def fetch(url, api_key, max_retries=5):
for attempt in range(max_retries):
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},
)
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")
if resp.status_code in (429, 503):
time.sleep(wait_seconds(resp, attempt))
continue
return resp
raise RuntimeError("Max retries exceeded")
Un quota journalier ne se réinitialise pas avant plusieurs heures, et un quota de période ne revient pas avant plusieurs jours. Traitez-les donc comme un arrêt plutôt que comme une simple attente. Lisez resets_at dans le body si vous souhaitez planifier la prochaine exécution.
Conseils
- Limitez le nombre de requêtes simultanées en cours au lieu de retenter un lot refusé. Une tempête de retries transforme un seul 429 en une multitude.
- Lisez
X-FourA-Limiten premier. Il vous indique en une seule chaîne si la limite provient de votre forfait ou de la plateforme, et aucun refus de la plateforme ne le définit. - Ne codez pas les valeurs en dur. Chaque réponse liée à une limite de forfait indique le plafond à l'origine du refus, et Usage & Limits les affiche tous.
retryAftersur les limites de plateforme est fixe selon le type : 2 secondes pour la concurrence, 5 pour le RPM, 60 pour la maintenance.- Fondez votre logique sur
errorpour distinguer les deux erreurs 503. Les deux structures comportentcurrentetlimits, donc vérifier simplement « ces champs existent-ils ? » interprétera une maintenance comme un problème de concurrence. - Une erreur 403 avec
X-FourA-Limitconcerne votre forfait, et non le site cible. La cible n'a jamais répondu.
Le port proxy a ses propres seuils
Tout ce qui précède concerne l'API JSON. Le trafic envoyé via proxy.foura.ai est soumis à un ensemble distinct de limites de forfait, exprimées dans une unité différente : tunnels ouverts simultanément, ouvertures de tunnels par minute, et trafic standard pour la période de facturation. Ces refus arrivent sous la forme d'un statut HTTP avec un header X-Foura-Error plutôt que sous forme de body JSON, car une commande CONNECT ne dispose d'aucun body pour en contenir un. Consultez Proxy Port pour le tableau des statuts et How Your Plan Is Metered pour savoir sur quel pool sont décomptés les gigaoctets du port.
Contenu connexe
- Run Requests in Parallel : un modèle complet de concurrence limitée
- Usage & Limits : chaque limite de forfait comparée à votre utilisation en direct
- API Endpoints : référence complète des paramètres
- Error Handling : tous les types d'erreurs et réponses
- Response Headers :
X-FourA-Limit,Retry-Afteret les autres - Troubleshooting : problèmes fréquents et solutions