Périmètre sûr : ce guide s'applique à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne traite pas des sites tiers.
Trois choses ont bougé sur reCAPTCHA v3 en 2026 : l'action envoyée avec le token compte autant que le score, la fenêtre pendant laquelle ce token reste utile s'est resserrée, et la vérification serveur renvoie des motifs de refus exploitables. Une intégration écrite en 2024 fonctionne toujours, mais elle échoue plus souvent en exécution planifiée qu'en démonstration. Voici les écarts observables et la façon d'y adapter une intégration CaptchaAI.
Ce qui a changé pour reCAPTCHA v3 depuis 2024
| Point de contrôle | Ancienne pratique | Ce qu'il faut faire en 2026 |
|---|---|---|
| Action | Un nom générique, submit partout |
Une action par parcours (login, checkout), transmise telle quelle |
| Durée de vie du token | Réutilisation pendant quelques minutes | Résolution à la demande, injection immédiate, aucun stockage |
| Vérification serveur | Un seuil de score | Le seuil, plus le motif de refus tracé dans vos logs |
| Session | Token obtenu ici, formulaire envoyé ailleurs | Même contexte, mêmes cookies, même client HTTP |
| Échec | Blocage silencieux | Bascule explicite vers reCAPTCHA v2, décidée dans votre code |
Aucune de ces lignes n'impose une réécriture. Elles expliquent pourquoi un flux stable depuis dix-huit mois renvoie soudain des scores bas, code inchangé.
Un cas concret : le formulaire de rendez-vous d'une équipe à Lyon
Une équipe QA héberge son application sur OVHcloud et lance chaque nuit, depuis un runner CI parisien, un test de bout en bout sur son formulaire de prise de rendez-vous. Depuis la mise à jour du script de chargement, il échoue une nuit sur trois : le token est obtenu, mais la route de validation le refuse.
Le diagnostic tient en une ligne de journal : le navigateur de test déclarait l'action homepage, héritée d'un ancien scénario, quand le backend attendait appointment. Le score n'était pas en cause. L'équipe en a profité pour purger les identifiants de session des journaux gardés plus de trente jours : ces traces servent au diagnostic, pas à l'archivage.
Architecture d'intégration recommandée
- Relevez les paramètres réels sur la page — sitekey, URL, nom d'action, rien de plus. Les valeurs approximatives créent des pistes de débogage fantômes.
- Envoyez la tâche à l'API CaptchaAI depuis votre composant interne, en HTTPS, avec un timeout explicite.
- Interrogez le résultat à intervalle fixe plutôt qu'en boucle serrée : une première attente, puis un polling régulier avec un plafond dur.
- Injectez le token dans la même session que celle qui a déclenché le défi : première cause de refus après une résolution réussie.
- Tracez la latence, les retries et l'acceptation en aval. Tâche résolue et parcours réussi sont deux mesures distinctes.
Où stocker la clé API CaptchaAI
La clé vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue, jamais dans le dépôt : le déploiement la monte en variable d'environnement au runtime. Côté capacité, la facturation est au thread. Le plan BASIC ($15/mois, 5 threads) couvre une suite de tests nocturne ; les paliers supérieurs servent aux workers parallèles.
Exemple : envoyer une tâche depuis votre suite de tests
Le squelette ci-dessous — clé lue dans l'environnement, tâche envoyée, identifiant récupéré — se réutilise pour reCAPTCHA v3 en adaptant le type de tâche et les paramètres attendus :
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
def submit_recaptcha_v2(sitekey: str, page_url: str) -> str:
payload = {
'clientKey': API_KEY,
'task': {
'type': 'NoCaptchaTaskProxyless',
'websiteURL': page_url,
'websiteKey': sitekey,
},
}
resp = requests.post('https://api.captchaai.com/createTask', json=payload, timeout=30)
resp.raise_for_status()
return resp.json()['taskId']
Instrumentez cet appel dès la première version : durée d'obtention du token, code retour HTTP, identifiant de tâche. Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry) pour rejouer un scénario complet.
Indicateurs à suivre sur reCAPTCHA v3
Les chiffres ci-dessous reposent sur des mesures observées et des retours d'utilisateurs. Les résultats varient selon l'environnement, le volume et le moment de la journée.
| Indicateur | Repère | Ce qu'il révèle |
|---|---|---|
| Temps de résolution reCAPTCHA v3 | < 4 s | La chaîne est saine et n'attend aucune nouvelle tentative |
| Taux de réussite du solveur | Élevé sur les types pris en charge | Vos paramètres correspondent au défi affiché |
| Acceptation en aval | Suivie séparément | La route de validation accepte le token dans la même session |
| Retries par tâche | Plafonnés à trois | Aucun défaut réel n'est masqué par une boucle |
Dépannage : symptômes fréquents
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Espace parasite ou mauvais compte | Recopiez la clé depuis le tableau de bord, en secret CI |
ERROR_ZERO_BALANCE |
Solde insuffisant | Rechargez, puis ajoutez une alerte de solde |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre manquant ou mal formé | Revalidez URL, sitekey et action face au HTML réel |
| Token refusé après résolution | Injection dans une autre session | Gardez résolution et envoi du formulaire dans le même contexte |
| Score systématiquement bas | Action déclarée différente de celle attendue | Alignez le nom d'action des deux côtés, puis remesurez |
Liste de contrôle avant mise en production
- Périmètre limité à vos applications ou à des sources autorisées.
- Clé API en coffre ou en secret CI, jamais dans le code source.
- Nom d'action identique côté page et côté vérification serveur.
- Durées d'appel et codes retour tracés à chaque exécution.
- Retry avec backoff exponentiel borné en place.
FAQ
Faut-il réécrire une intégration reCAPTCHA v3 datant de 2024 ?
Non, dans la plupart des cas. Vérifiez trois points : le nom d'action, la session d'injection du token, le traitement des refus côté serveur. Une intégration qui aligne ces trois éléments tient encore.
Quel seuil de score retenir pour reCAPTCHA v3 ?
Il n'existe pas de valeur universelle : le seuil dépend de votre trafic. Mesurez la distribution des scores par action sur deux semaines, puis placez le seuil pour limiter les refus légitimes, avec une bascule vers reCAPTCHA v2 plutôt qu'un blocage sec.
CaptchaAI prend-il en charge hCaptcha si le site change de famille de CAPTCHA ?
Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge. Les familles couvertes sont reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, les CAPTCHA image, OCR et grilles ; GeeTest v4 est annoncé à venir, et CaptchaFox, Friendly Captcha et Lemin sont en bêta.
Que conserver dans les journaux sans alourdir les obligations RGPD ?
Gardez l'identifiant de tâche, l'horodatage, la durée et le code retour. Ne conservez ni le token, ni l'adresse IP brute, ni les identifiants de session au-delà de la fenêtre de diagnostic utile.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester vos endpoints de formulaire
- Le CAPTCHA en intégration continue
- Résoudre reCAPTCHA v2 via l'API
Commencez par une seule action, mesurez-la pendant une semaine, puis étendez. – Obtenez votre clé CaptchaAI.
