Résultats des requêtes
Chaque request envoyée à l'API FourA est classée selon un résultat unique, tout comme chaque tunnel via le port de proxy. Ce résultat est calculé une seule fois, à la fin de l'appel, et enregistré pour l'identifiant qui l'a émis. Votre tableau de bord, votre flux d'activité et votre facturation lisent tous ce même champ.
Seul success coûte des crédits. Le trafic premium est décompté indépendamment des crédits et ne dépend pas du résultat: consultez Billing Implications.
Les sept résultats
Voici les sept états dans lesquels une request peut se terminer. Un tunnel en utilise cinq: consultez Tunnels Use the Same Vocabulary ci-dessous.
| Résultat | Couche | Signification |
|---|---|---|
success |
n/a | Une response valide a été transmise. Décompté de votre quota facturable. |
application_error |
target | La cible a renvoyé un statut HTTP 200, mais le body contenait un champ d'erreur, ou le body correspond à une vérification anti-bot ou une page de refus reconnue par FourA. |
application_fail |
target | La cible a renvoyé un statut différent de 200 que vos règles validate n'ont pas accepté ou pour lequel vous n'avez pas défini de validate, ou n'a renvoyé aucune response, y compris un nom d'hôte cible impossible à résoudre. |
client_error |
caller | Votre request a été rejetée avant de quitter FourA. Paramètres invalides, valeur de proxy malformée, URL bloquée par la protection SSRF. |
rate_limit |
FourA | La request a été refusée avant son exécution: par l'une des limites de votre forfait (un statut 403 pour un endpoint ou un paramètre non inclus dans le forfait, un statut 429 pour un quota épuisé), ou par le quota partagé de la plateforme en RPM ou en concurrence. |
service_error |
FourA | Le moteur a répondu par une erreur de serveur, ou son body n'était pas un JSON valide. |
service_fail |
FourA | Le réseau propre de FourA a rencontré une défaillance: son moteur n'a pas répondu à temps, la connexion a été interrompue ou vous vous êtes déconnecté. |
La colonne de la couche indique qui est responsable:
- Les résultats de type target concernent le site que vous avez appelé. Votre request a bien atteint FourA, et FourA a bien atteint la cible. C'est la cible elle-même qui a renvoyé une erreur.
- Les résultats de type caller indiquent que votre request ne pouvait pas aboutir. Corrigez le format de la request.
- Les résultats de type FourA relèvent de notre responsabilité. Réessayez, et vérifiez la status page si le problème persiste.
Un site cible qui renvoie 403 correspond à application_fail, et non à client_error. Votre appel était bien formé. Le site a simplement refusé.
À quoi ressemble un appel en échec
Un appel qui a atteint FourA et s'est exécuté renvoie un statut HTTP 200, quelle que soit la suite des événements. Seul un refus avant la récupération (400, 401, 403, 413, 429) ou une défaillance côté FourA (5xx) utilise un autre statut HTTP. Le résultat se lit donc dans le body, et non dans le statut de transport.
| Corps | Ce qui s'est passé | Résultat |
|---|---|---|
status: 200, headers, data, pas de error |
La page a été livrée. | success |
status autre que 200, headers, data, pas de error |
La cible a répondu et vous n'avez envoyé aucun validate. Sa réponse se trouve dans data. |
application_fail |
status autre que 200, headers, data et error |
La cible a répondu et vos règles validate l'ont rejetée, par exemple Status 404 is not in accept list 200. |
application_fail |
status: 200, headers, data et error |
La cible a répondu HTTP 200 et vos règles validate l'ont rejetée, par exemple Data not in accept list ["product"]. |
application_error |
error et total_time uniquement, pas de status, pas de data |
La cible n'a jamais répondu en HTTP : la limite de redirections a été atteinte (Number of redirects hit maximum amount), la connexion ou la lecture a expiré, la connexion a été réinitialisée ou la réponse était vide. Le texte correspond à la raison propre du moteur. |
application_fail |
status: 0 et error, rien d'autre |
Le nom d'hôte ne peut pas être résolu : could not resolve <host>: <reason>. Aucun moteur n'a fonctionné, et en mode Auto il n'y a pas de meta. Réessayer ne changera rien tant que le DNS ne change pas. |
application_fail |
Une boucle de redirection, telle que vue par la cinquième ligne :
{
"error": "Number of redirects hit maximum amount",
"total_time": 0.808
}
Sur POST /api/proxy/, un appel qui épuise ses tentatives renvoie error: Download maxTry limit reached et un attemptReport avec les compteurs (voir Erreurs d'API). Sur POST /api/auto/, un ladder exécuté ayant échoué renvoie status, error, attempts, un attemptReport avec les causes, et meta.rung défini sur fail.
X-FourA-Credits rapporte le travail effectué, y compris en cas d'échec. La facturation ne prend en compte que success, aucun des cas d'échec ci-dessus n'est donc facturé.
Le succès s'adapte à validate
Sans validate, l'API marque une request comme success uniquement lorsque la cible renvoie un code HTTP 200.
Avec validate, le succès suit les règles que vous avez déclarées. Si vous indiquez à l'API que 200 et 403 sont tous deux acceptables pour une request donnée, un 403 est renvoyé comme success. Le corps de la réponse vous parvient toujours sans modification.
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://target.example/feed",
"validate": {
"status": { "accept": [200, 403] }
}
}'
Dans cet appel, une réponse 403 compte comme success et est facturée comme une requête. Une réponse 500 compte comme application_fail et n'est pas facturée.
La même logique s'applique à validate.headers et validate.data. Toute réponse que le moteur accepte selon vos règles revient sous la forme success quel que soit le statut HTTP.
Une réponse n'est jamais success, avec ou sans validate: un HTTP 200 dont le corps est une page de vérification de bot reconnue par FourA, comme une tâche de vérification visuelle, une page demandant uniquement au navigateur d'exécuter du JavaScript, ou une page de refus renvoyée par un site avec un code HTTP 200. Cette requête est application_error et n'est pas facturée. Le corps vous parvient tout de même sans modification, et le header X-FourA-Check-Page nomme la page.
Implications sur la facturation
| Résultat | Facturable | Décompté du quota |
|---|---|---|
success |
Oui | Oui |
application_error |
Non | Non |
application_fail |
Non | Non |
client_error |
Non | Non |
rate_limit |
Non | Non |
service_error |
Non | Non |
service_fail |
Non | Non |
Seules les requêtes ayant fourni les données demandées sont facturées. Les échecs du côté de FourA, de la cible ou de votre côté sont tous gratuits.
Ce tableau concerne les crédits. Le trafic premium est comptabilisé séparément: une requête ayant tenté une sortie premium comptabilise le trafic acheminé par cette tentative, quel que soit le résultat, car la sortie a bien été utilisée. Une tentative encore en cours au moment où une autre sortie répond est immédiatement interrompue, et le trafic acheminé jusque-là est également comptabilisé.
Le trafic standard ne dépend pas non plus du résultat: avec un forfait assorti d'une limite de bande passante, le trafic de chaque requête est décompté de cette limite. Une requête refusée en raison d'une limite de votre forfait ne consomme aucun trafic.
Les tunnels utilisent le même vocabulaire
Un tunnel via le port de proxy se termine également par l'un de ces résultats; un même ensemble d'étiquettes couvre donc les deux produits. Seuls cinq des sept états peuvent survenir, car les deux résultats target nécessitent que FourA ait analysé la réponse de la cible, alors que la réponse d'un tunnel correspond à votre propre trafic chiffré.
| Résultat | Signification pour un tunnel |
|---|---|
success |
Le tunnel s'est ouvert et votre outil l'a récupéré. |
client_error |
FourA refuse d'ouvrir ce tunnel: adresse privée ou réservée, ou port non pris en charge. |
rate_limit |
Une limite de votre forfait a été atteinte (tunnels ouverts simultanément, ouvertures de tunnel par minute, volume de trafic standard sur la période, trafic premium non souscrit), ou le port lui-même a atteint sa capacité ou son taux d'ouverture maximal. |
service_error |
FourA ne disposait d'aucune sortie correspondant à votre demande. Généralement temporaire. |
service_fail |
La cible est restée inaccessible via toutes les sorties tentées par FourA: DNS, timeout, connexion refusée. |
application_error |
Ne se produit jamais sur un tunnel. |
application_fail |
Ne se produit jamais sur un tunnel. |
Un refus s'accompagne également d'un motif court, et le tableau de bord l'affiche selon vos propres termes plutôt que les nôtres. Une option que FourA ne peut pas honorer reçoit une réponse 400 sur la connexion elle-même et n'écrit aucune ligne, elle n'apparaît donc jamais ici.
| Motif à l'écran | Limite atteinte |
|---|---|
| port not in plan | Votre forfait n'inclut pas le port proxy |
| tunnels at once | Tous les tunnels simultanés autorisés par votre forfait étaient utilisés |
| openings per minute | Les ouvertures de tunnel de votre forfait pour cette minute ont été épuisées |
| traffic used up | Le trafic de votre forfait pour cette période est épuisé |
| premium not available | Le trafic premium n'est pas disponible sur votre forfait pour le moment |
| port was full | Le port lui-même a atteint sa capacité ou son taux d'ouverture. Réessayez dans un instant. |
| port not served | FourA n'ouvre pas de tunnels vers ce port |
| private address | Les adresses privées et réservées ne peuvent pas être atteintes |
Aucun élément lié à un tunnel n'est facturé en crédits, car un tunnel ne comporte aucune requête à laquelle imputer un coût. Le port mesure les octets à la place. Consultez Comment votre forfait est mesuré.
Consulter les résultats dans le tableau de bord
Chaque requête effectuée par votre clé d'API apparaît dans le flux Activité avec son libellé de résultat. Les pages Métriques et Vue d'ensemble agrègent le même champ pour les graphiques en anneau et les chronologies.
Lorsque vous filtrez l'Activité par résultat, vous pouvez aussi cibler un seul endpoint (Auto, Single, Proxy Finder, Browser) pour vérifier si une catégorie d'échec est spécifique à l'un d'eux. Basculez le champ Produit de la page sur Proxy et les mêmes pastilles de résultat filtreront vos tunnels.
Heuristiques de nouvelle tentative
Une politique de nouvelle tentative de premier niveau basée sur les résultats :
| Résultat | Nouvelle tentative sûre ? | Quand |
|---|---|---|
success |
n/a | Vous disposez de la réponse. |
application_error |
Parfois | Lisez le corps d'erreur de la cible. Certaines erreurs sont temporaires, la plupart ne le sont pas. Si X-FourA-Check-Page est défini, le site a renvoyé une page de vérification : envoyez l'URL à Auto, qui traite une page de vérification comme une étape à franchir, et non comme la réponse. |
application_fail |
Parfois | Si la cible applique un rate limit, ralentissez. Si elle vous bloque, passez à l'endpoint Proxy ou Browser. |
client_error |
Non | La requête échouera à nouveau de la même manière. Corrigez les données en entrée. |
rate_limit |
Dépend | Respectez le temps d'attente indiqué par la réponse : Retry-After, retry_after_seconds ou retryAfter. Avec plan_limit_browser_daily, suspendez les envois jusqu'à minuit UTC ; avec plan_limit_credits ou plan_limit_bandwidth, suspendez les envois jusqu'à resets_at ; avec plan_limit_feature ou plan_limit_premium, modifiez la requête. |
service_error |
Oui | Backoff exponentiel court. |
service_fail |
Oui | Identique à service_error. |
Liens associés
- Erreurs d'API : Réponses d'erreur au niveau HTTP
- Port Proxy : Codes de statut retournés lors du refus d'un tunnel
- Rate Limits : Événements déclencheurs de
rate_limitet ses deux formats de réponse - Métriques : Emplacement où consulter le détail des résultats
- Journal d'activité : Historique des résultats par request