Limite de tâches simultanées et suspension automatique

Pour que la reconnaissance reste rapide pour tous les utilisateurs, YesCaptcha applique trois règles de protection : une limite du nombre de tâches en cours de traitement simultanément par compte (limite de tâches simultanées) ; une suspension de quelques minutes pour un clientKey qui génère trop d’erreurs en peu de temps (suspension automatique) ; et un cache des paramètres déjà jugés invalides, qui renvoie l’erreur d’origine pendant un certain temps (cache des paramètres invalides). Aucun de ces trois cas n’entraîne de débit de points.

Limite de tâches simultanées

Nous limitons, par compte et par type de tâche, le nombre de tâches en cours de traitement au même instant. Il s’agit d’une limite de tâches simultanées, pas d’un nombre de requêtes par minute.

• Une tâche est « en cours » depuis l’appel de createTask jusqu’au retour de cet appel. Les types de reconnaissance d’images renvoient le résultat directement dans createTask, donc nombre de tâches simultanées ≈ tâches envoyées par seconde × durée de chaque tâche. Par exemple, avec 0.5 seconde par tâche et 40 tâches par seconde, on obtient environ 20 tâches simultanées.
• Les requêtes d’un même compte sont comptées ensemble ; chaque type de tâche est compté séparément.
• Les requêtes au-delà du quota renvoient immédiatement ERROR_THREADS_MAXIMUM, et limit dans la réponse indique votre limite actuelle. Aucun débit de points, et la requête n’est pas comptée pour la suspension automatique.
• Quand les serveurs de reconnaissance sont surchargés, pour le compte qui consomme le plus de temps de reconnaissance, la limite de ce type de tâche est temporairement divisée par deux, puis rétablie automatiquement après 10 minutes. Il s’agit seulement d’un ralentissement ; le compte n’est pas suspendu.
• Pour obtenir un quota plus élevé, contactez le support. Une fois les quotas par défaut de chaque type définis, ils seront publiés sur cette page et dans le journal des mises à jour du service.

{
  "errorId": 1,
  "errorCode": "ERROR_THREADS_MAXIMUM",
  "errorDescription": "This account already has 30 tasks of this type in progress, which is the limit. Lower the concurrency and wait for pending requests to return before sending more; rejected requests are not charged and do not lead to a block.",
  "limit": 30
}

(Les nombres de l’exemple sont donnés à titre indicatif.)

Bonnes pratiques

1. Limitez dans votre programme le « nombre de requêtes en attente de résultat en même temps », par exemple avec un sémaphore (Semaphore) ou un pool de threads de taille fixe, plutôt que de ne contrôler que le nombre de requêtes par seconde.
2. Après un ERROR_THREADS_MAXIMUM, attendez que les requêtes déjà envoyées reviennent avant d’en envoyer de nouvelles, ou patientez 1 à 2 secondes avant de réessayer. Ne réessayez pas immédiatement en boucle.
3. Répartissez les tâches en lot de façon régulière ; n’envoyez pas des milliers de tâches d’un coup.

Exemple en Python (asyncio) :

import asyncio
import os

import aiohttp

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15  # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)


async def solve(session, task):
    async with sem:  # at most LIMIT requests in progress at a time
        result = {}
        for attempt in range(5):
            async with session.post(
                "https://api.yescaptcha.com/createTask",
                json={"clientKey": CLIENT_KEY, "task": task},
            ) as resp:
                result = await resp.json()
            if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
                return result
            await asyncio.sleep(1 + attempt)  # over the limit: wait and retry
        return result

Suspension automatique

Lorsqu’un même clientKey génère un grand nombre de requêtes en erreur en peu de temps, la création de tâches est automatiquement suspendue :

Condition de déclenchement	Durée de la suspension
100 erreurs de la liste ci-dessous au cours de la même minute calendaire	5 minutes
1 occurrence de ERROR_IMAGE_TYPE_NOT_SUPPORTED	30 minutes
1,000 correspondances avec le « cache des paramètres invalides » au cours de la même minute calendaire	5 minutes

Erreurs comptant pour la suspension :

• ERROR_REQUEST_FORMATS
• ERROR_TASK_ABSENT
• ERROR_TASK_NOT_SUPPORTED
• ERROR_KEY_DOES_NOT_EXIST
• ERROR_KEY_EXPIRED
• ERROR_TASKID_INVALID
• ERROR_SETTLEMENT_FAILED
• ERROR_HIGH_DEMAND_DOMAIN
• ERROR_ZERO_CAPTCHA_FILESIZE
• ERROR_TOO_BIG_CAPTCHA_FILESIZE
• ERROR_IMAGE_TYPE_NOT_SUPPORTED
• ERROR_ILLEGAL_IMAGE

L’erreur ERROR_THREADS_MAXIMUM renvoyée lorsque la limite de tâches simultanées du compte est dépassée (avec le champ limit) n’est pas comptée ; l’erreur du même nom renvoyée quand le service de reconnaissance est surchargé (sans limit) l’est. Les échecs de reconnaissance (ERROR_CAPTCHA_UNSOLVABLE), le solde insuffisant (ERROR_ZERO_BALANCE), les champs manquants (ERROR_REQUIRED_FIELDS), les questions non prises en charge (ERROR_UNKNOWN_QUESTION) et autres ne sont pas comptés.

Pendant la suspension :

• Seuls createTask et getBalance sont concernés, et renvoient ERROR_IP_BLOCKED_5MIN. getTaskResult n’est pas affecté : les tâches créées avant la suspension peuvent toujours être consultées.
• La réponse contient retryAfter (nombre de secondes restantes), blockReason (le code d’erreur qui a déclenché la suspension) et blockDetail (le type, l’URL et le sitekey de ces requêtes) ; utilisez-les pour corriger votre programme.
• Continuer à envoyer des requêtes ne prolonge pas la suspension, qui se termine automatiquement à l’échéance ; il n’est pas nécessaire de contacter le support.
• Le Tableau de bord sur yescaptcha.com affiche les suspensions des dernières 24 heures.

{
  "errorId": 1,
  "errorCode": "ERROR_IP_BLOCKED_5MIN",
  "errorDescription": "...",
  "retryAfter": 182,
  "blockReason": "ERROR_TASK_NOT_SUPPORTED"
}

Cache des paramètres invalides

Certaines erreurs dépendent des paramètres de la requête : renvoyer les mêmes paramètres donnera le même résultat :

• ERROR_RECAPTCHA_INVALID_SITEKEY
• ERROR_RECAPTCHA_INVALID_DOMAIN
• ERROR_INVALID_KEY_TYPE
• ERROR_DOMAIN_NOT_ALLOWED

Ces erreurs ne comptent pas pour la suspension automatique ; elles sont mises en cache pour l’ensemble du site : 2 minutes après le premier constat, et 10 minutes si elles sont de nouveau confirmées dans l’heure. Pendant la durée du cache, une requête identique (même type de tâche et même websiteKey, ou même nom de domaine) renvoie directement l’erreur d’origine, sans débit de points, avec "cached": true, retryAfter (secondes restantes dans le cache) et badRequest (le paramètre concerné). La correction du websiteKey ou le changement de type de tâche prend effet immédiatement.

Différence entre limite de tâches simultanées et suspension automatique

	Limite de tâches simultanées	Suspension automatique
Cause	Trop de tâches en cours de traitement en même temps	Trop de requêtes en erreur en peu de temps
Effet	Seules les requêtes excédentaires sont rejetées, avec ERROR_THREADS_MAXIMUM	Ce clientKey ne peut plus créer de tâches, ERROR_IP_BLOCKED_5MIN
Rétablissement	Dès qu’une requête est terminée, vous pouvez en envoyer une nouvelle ; la réduction de moitié est levée après 10 minutes	Levée automatique à l’échéance
Débit de points	Non	Non