验证码 API 报错时，日志通常只告诉你哪一步失败，却看不到实际发出的 HTTP 请求。更快的办法是用 Charles Proxy 抓一次包——请求头、请求体、响应内容和每一跳耗时一目了然，几秒就能看出到底是参数传错、sitekey 提取失败，还是网络问题。
一个国内常见场景：reCAPTCHA 请求为什么总是超时
国内开发者最常遇到的不是 CaptchaAI 报错，而是轮询迟迟拿不到结果。打开 Charles 看一眼：ocr.captchaai.com 耗时正常（几十到几百毫秒）就说明 CaptchaAI 没问题，真正卡住的多半是浏览器加载 reCAPTCHA 资源那一步——资源托管在 Google，国内访问本身不稳定。国内常见的 GeeTest（极验）不用连 Google，两条链路的排查思路并不一样。
提示：先看
ocr.captchaai.com耗时，能省掉大半排查时间。
环境准备：让 Charles 接管你的请求
步骤一：安装 Charles Proxy
从 Charles 官网 下载，支持 Win/Mac/Linux。
步骤二：开启 SSL 抓包
CaptchaAI 走 HTTPS，需要两步。
添加代理规则
- Proxy → SSL Proxying Settings → Add
- Host 填
ocr.captchaai.com，Port 填443
安装并信任证书
- Help → SSL Proxying → Install Charles Root Certificate
- 在系统证书库里信任该证书
步骤三：让代码走 Charles 代理
Charles 默认监听 localhost:8888。
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,
});
提交请求怎么核对（POST /in.php）
点开 /in.php 这条请求，核对以下几项：
- Request → Headers：Content-Type 是否正确
- Request → Body：必需参数是否齐全
- Response → Body：成功时应返回
{"status":1,"request":"TASK_ID"} - Timing：请求耗时，正常应 < 1s
最容易漏掉的一项：请求体写成了 JSON 而不是表单数据——
/in.php只接受表单编码。
常见问题：
- 缺少
method参数 → 返回ERROR_BAD_PARAMETERS - Content-Type 不对 → 参数没有被正确解析
googlekey为空 → 返回ERROR_WRONG_GOOGLEKEY
轮询请求怎么核对（GET /res.php）
- 参数：
key、action=get、id=TASK_ID是否都在 - 响应：未完成时返回
CAPCHA_NOT_READY（继续轮询），完成后返回{"status":1,"request":"TOKEN"} - 耗时：每次轮询的间隔应等于你在代码里设置的 sleep 时间，如果间隔忽长忽短，多半是重试逻辑有问题
常见故障速查
- 代码里报 SSL 错误 → 证书不受信任 → 安装 Charles 根证书，开发阶段可先用
verify=False - Charles 里看不到请求 → 代码没走代理 → 在 requests / axios 配置里显式设置 proxy
- HTTPS 响应乱码 → 没开 SSL 抓包 → 把
ocr.captchaai.com加到 SSL Proxying Settings - 请求变慢了 → 断点还开着 → 不需要时记得关掉
调试常见问题
问题一：ERROR_WRONG_GOOGLEKEY
在 Charles 里打开提交请求的请求体，找到 googlekey 字段：
# What Charles shows:
key=YOUR_API_KEY&method=userrecaptcha&googlekey=&pageurl=https://example.com&json=1
^^^^^^^^ empty!
修复：上游 sitekey 提取逻辑有问题，检查提取代码。
问题二：token 被目标站点拒绝
先确认 token 本身没问题
- 在 Charles 里找到
status: 1的/res.php响应 - 从
request字段完整复制 token
再确认 token 用对了地方
- 找到发往目标站点的后续请求
- 确认表单字段名是
g-recaptcha-response，值和上一步一致
多数是变量没及时更新，用的还是旧 token。
问题三：请求一直超时
用 Charles 的 Sequence 视图看时间线：
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
一直卡在 CAPCHA_NOT_READY：先确认 sitekey 和 pageurl 正确，再参考前文排查网络可达性。
Charles 进阶调试技巧
重复请求（Repeat）
右键请求 → Repeat 重新发送，测试轮询不用重跑整个脚本。
断点（Breakpoints）
- Proxy → Breakpoint Settings → Add
- Host 填
ocr.captchaai.com，Path 填/in.php - 勾选 Request，代码发请求时会先暂停，可直接改参数再放行
调试完记得关掉断点——忘记关闭是"Charles 让请求变慢了"的常见原因。
Map Local（本地映射）
把 API 响应换成本地文件测试：
{"status": 1, "request": "mock_token_for_testing"}
- Tools → Map Local → Add
- 把
https://ocr.captchaai.com/res.php映射到本地的mock_response.json - 不消耗 API 额度即可测试提交代码
限速（Throttle）
- Proxy → Throttle Settings → 启用
- 预设选 3G 或 EDGE 速度，验证慢响应和超时处理
Charles 之外还能用什么抓包工具
| 工具 | 平台 | HTTPS | 费用 |
|---|---|---|---|
| Charles Proxy | Win/Mac/Linux | 需要安装证书 | 付费（有免费试用） |
| mitmproxy | Win/Mac/Linux | 需要安装证书 | 免费 |
| Fiddler | Windows | 内置 HTTPS 解密 | 免费 |
| Proxyman | macOS | 一键完成 HTTPS 配置 | 免费增值 |
mitmproxy 快速上手
# Install
pip install mitmproxy
# Run
mitmproxy --listen-port 8080
# Configure Python
proxies = {"https": "http://localhost:8080"}
国内安装慢的话换清华 TUNA 镜像：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mitmproxy。
常见问题
reCAPTCHA 相关请求经常超时，是网络问题还是 CaptchaAI 的问题？
先看 Charles 里的耗时。/in.php、/res.php 都很快的话，卡点在浏览器加载 reCAPTCHA 资源，是网络问题，不是 CaptchaAI。
生产环境要不要一直开着 Charles？
不需要。它是开发调试工具，长期挂着会拖慢请求，生产环境用结构化日志和监控即可。
抓包看到的 token 和实际提交的不一样，怎么排查？
对比 /res.php 返回的完整 token 与表单请求里 g-recaptcha-response 字段，多数是变量没及时更新。
调试完，直接用 CaptchaAI 验证结果
去 CaptchaAI 官网 拿到 API Key，把这套抓包方法用到自己的集成里。
相关指南
- CAPTCHA 操作的结构化日志实践
- CaptchaAI 错误码对照表
- CaptchaAI API 测试用 Postman 合集
