Runbook d'incident pour l'extension CaptchaAI

Quand l'extension CaptchaAI cesse de répondre en pleine campagne de tests, la bonne réaction n'est pas de recharger la page : c'est de basculer vers l'API et de dérouler un runbook déjà écrit. L'extension n'est qu'une couche de confort ; le chemin durable reste l'appel HTTPS que vous pilotez. Ce guide décrit le diagnostic, la bascule et les mesures pour qu'un incident ne bloque jamais un workflow critique.

Périmètre sûr : ce runbook s'applique uniquement à vos propres applications et environnements (QA, préproduction, production) ou à des systèmes pour lesquels vous détenez une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni la levée de protections anti-bot sur des sites que vous ne contrôlez pas.

Extension CaptchaAI ou API : localiser la panne

L'extension CaptchaAI et l'API partagent le même compte et le même solde, mais par des chemins différents : l'extension injecte le token dans le navigateur, l'API expose le même moteur via un appel HTTPS que votre code déclenche. Face à une panne, cherchez la cause dans l'extension, le profil de navigateur, le compte (clé ou solde) ou la page cible.

Réagir à un incident : la séquence à dérouler

Déroulez toujours la même séquence — elle transforme un incident stressant en routine.

1. Vérifiez le compte. Un appel getBalance (ci-dessous) confirme que la clé est valide et que le solde n'est pas nul.
2. Capturez les paramètres exacts attendus par la famille de CAPTCHA (sitekey, URL, action, proxy éventuel) ; en stocker plus crée de fausses pistes.
3. Soumettez la tâche à l'endpoint in.php avec json=1, et traitez tout statut différent de 1 comme une erreur à journaliser.
4. Interrogez le résultat sur res.php : attendez 15 s, puis interrogez toutes les 5 s, plafond à 120 s par tâche.
5. Appliquez le token dans la même session que le défi (même navigateur, même client HTTP, mêmes cookies) : une session dépareillée est la première cause de rejet.

Vérifier le compte en une requête

Premier réflexe : confirmer que le compte est sain. L'exemple ci-dessous lit le solde et échoue si la requête ne passe pas.

import os
import requests

API_KEY = os.environ['CAPTCHAAI_KEY']

def get_balance() -> float:
    resp = requests.post(
        'https://api.captchaai.com/getBalance',
        json={'clientKey': API_KEY},
        timeout=15,
    )
    resp.raise_for_status()
    return float(resp.json().get('balance', 0))

Un solde correct et un code 200 écartent le compte : concentrez le diagnostic sur le profil de navigateur ou la page cible.

Observabilité et KPI d'incident

Instrumentez chaque appel CAPTCHA — durée d'obtention du token, code retour HTTP, identifiant de tâche — et séparez les journaux par environnement, corrélés à votre traçage distribué (OpenTelemetry). Fixez des cibles : latence p50 sous 25 s pour les CAPTCHA à token (8 s en OCR d'image), p95 sous 60 s, réussite et acceptation en aval au-delà de 95 %.

Liste de contrôle avant la mise en production

• Périmètre limité à vos applications ou à des sources autorisées.
• Clé CaptchaAI dans un coffre ou un secret CI, jamais dans le code.
• Interrogation : 15 s d'attente, puis toutes les 5 s, plafond 120 s.
• Résolution et envoi du formulaire dans la même session, retries plafonnés à trois avec backoff exponentiel.

Dépannage : codes d'erreur courants

FAQ

Que faire immédiatement quand l'extension CaptchaAI ne répond plus ?

Vérifiez d'abord le compte avec getBalance : clé valide, solde non nul. Si le compte est sain, basculez vos tests vers l'API le temps de diagnostiquer le profil de navigateur.

L'extension et l'API partagent-elles la même clé et le même solde ?

Oui : les deux consomment le même compte CaptchaAI, avec le solde et les threads mutualisés. La bascule ne demande donc aucune nouvelle configuration de facturation, seulement la même clé côté serveur.

Comment distinguer une panne de l'extension d'un problème sur la page cible ?

Rejouez la résolution via l'API sur la même page. Si l'API obtient un token accepté, la panne est côté extension ou profil de navigateur ; si l'API échoue aussi, vérifiez vos paramètres d'entrée et la famille de CAPTCHA. Pour un workflow critique, prévoyez un repli automatique vers l'API après un court délai d'expiration.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégrer la résolution CAPTCHA à votre CI
• Résoudre reCAPTCHA v2 via l'API

Ne laissez plus une panne d'extension bloquer vos tests. — Créez votre compte CaptchaAI.