Débogage des appels API CAPTCHA avec Charles Proxy

Charles Proxy vous montre ce que votre code envoie à CaptchaAI et ce que l'API renvoie : corps de requête, en-têtes, codes de réponse et timing. Quand une intégration reCAPTCHA ou Turnstile échoue sans message clair, ce trafic HTTP brut révèle où le problème se cache — un paramètre absent, un googlekey vide ou un token jamais injecté.

Placé entre votre script et ocr.captchaai.com, Charles intercepte chaque échange. Ce guide le configure pour le HTTPS, corrige les erreurs fréquentes, puis vérifie chaque requête.

Installer et configurer Charles Proxy

1. Installez Charles Proxy

Téléchargez-le depuis le site officiel de Charles Proxy. Il fonctionne sur Windows, macOS et Linux ; l'essai gratuit suffit pour une session de débogage.

2. Activez le proxy SSL pour le HTTPS

CaptchaAI communique en HTTPS : sans déchiffrement, Charles n'affiche qu'un tunnel illisible. Pour lire les échanges avec ocr.captchaai.com :

3. Faites passer votre code par Charles

Par défaut, Charles écoute sur localhost:8888. Pointez-y votre client HTTP.

Python :

import requests

proxies = {
    "http": "http://localhost:8888",
    "https": "http://localhost:8888",
}

# Disable SSL verification for Charles (development only)
resp = requests.post(
    "https://ocr.captchaai.com/in.php",
    data={"key": "YOUR_API_KEY", "method": "userrecaptcha", "json": "1"},
    proxies=proxies,
    verify=False,
)

Node.js :

const axios = require('axios');
const HttpsProxyAgent = require('https-proxy-agent');

const agent = new HttpsProxyAgent('http://localhost:8888');

const resp = await axios.post('https://ocr.captchaai.com/in.php', null, {
  params: { key: 'YOUR_API_KEY', method: 'userrecaptcha', json: 1 },
  httpsAgent: agent,
});

verify=False désactive la vérification TLS pour accepter le certificat de Charles ; réservez-le au dev local.

Résoudre les erreurs les plus fréquentes

La plupart des pannes se lisent dans le trafic capturé.

ERROR_WRONG_GOOGLEKEY : un sitekey vide

Cas typique : chez une équipe QA à Lyon, cette erreur surgit quand le sitekey est injecté tardivement par JavaScript. Ouvrez le corps de la requête d'envoi et repérez le champ googlekey :

# What Charles shows:
key=YOUR_API_KEY&method=userrecaptcha&googlekey=&pageurl=https://example.com&json=1
                                      ^^^^^^^^ empty!

Correctif : l'extraction du sitekey a échoué en amont. Vérifiez le code qui lit la clé et attendez que l'élément soit présent avant de la lire.

Requêtes qui expirent

Ouvrez la vue Sequence de Charles pour visualiser le timing de bout en bout :

POST /in.php     → 234ms ✓
GET  /res.php    → 189ms (CAPCHA_NOT_READY)
GET  /res.php    → 201ms (CAPCHA_NOT_READY)
GET  /res.php    → 195ms (CAPCHA_NOT_READY)
... 23 more ...
GET  /res.php    → 188ms (CAPCHA_NOT_READY)  ← never resolves

Si la tâche ne se résout jamais, le sitekey ou l'URL sont probablement erronés : recoupez-les avec le corps de /in.php.

Token refusé par le site cible

Le token est bien renvoyé, mais le site le rejette. Comparez la réponse de l'API et ce que vous injectez :

Vérifier méthodiquement chaque requête

Pour les pannes moins évidentes, passez chaque appel en revue.

La requête d'envoi (POST /in.php)

Sélectionnez l'appel /in.php et contrôlez chaque onglet :

Les symptômes les plus courants :

La requête de polling (GET /res.php)

Inspectez ensuite les requêtes qui interrogent le résultat :

Côté RGPD, une session capture le trafic en clair : ne conservez pas les sessions contenant des données personnelles au-delà du débogage.

Les fonctions Charles utiles au débogage CAPTCHA

Rejouer une requête

Clic droit sur une requête → Repeat pour la renvoyer. Pratique pour tester les interrogations /res.php sans relancer tout votre script.

Points d'arrêt

Un point d'arrêt sur /in.php met le code en pause avant l'envoi : ajustez les paramètres à la volée.

Map Local : simuler les réponses de l'API

Map Local sert une réponse locale : votre code d'injection de token s'exécute sans mobiliser un thread.

{"status": 1, "request": "mock_token_for_testing"}

Throttle : simuler un réseau lent

Throttle reproduit une connexion dégradée pour éprouver vos timeouts :

Charles, mitmproxy ou une autre alternative ?

Charles est confortable mais payant. D'autres outils rendent le même service :

Configuration rapide de mitmproxy

# Install
pip install mitmproxy

# Run
mitmproxy --listen-port 8080

# Configure Python
proxies = {"https": "http://localhost:8080"}

Dépannage

FAQ

Comment inspecter le trafic HTTPS chiffré de CaptchaAI ?

Installez le certificat racine de Charles, approuvez-le, puis ajoutez ocr.captchaai.com aux SSL Proxying Settings. Sans cela, le trafic reste chiffré.

Peut-on tester son intégration sans consommer de crédits ?

Oui. Utilisez Map Local pour associer /res.php à un fichier JSON simulé : votre code d'injection de token s'exécute sans mobiliser un thread.

Charles peut-il capturer des données personnelles ?

Oui, une session enregistre le trafic en clair. Par prudence RGPD, évitez les identifiants réels et supprimez ensuite les sessions.

Faut-il garder Charles en production ?

Non. Charles est un outil de développement. En production, appuyez-vous sur la journalisation structurée et la surveillance.

Déboguez et optimisez votre intégration CaptchaAI

Obtenez votre clé API sur captchaai.com et rejouez vos appels jusqu'à un trafic propre.

Guides associés

• La journalisation structurée pour les opérations CAPTCHA
• La référence des codes d'erreur CaptchaAI
• La collection Postman pour tester l'API CaptchaAI