Callback от CaptchaAI не долетел, ваш сервер лежал в этот момент или обработчик упал при записи результата — решённый токен при этом никуда не девается: CaptchaAI хранит его на res.php, и его всегда можно забрать резервным опросом. Вопрос не в том, «доверять ли callback», а в том, как выстроить приём результата так, чтобы недоступность вашего сервера на 30 секунд или на 5 минут не превращалась в потерянное решение CAPTCHA. Ниже — три паттерна, которые в связке закрывают эту задачу: резервный опрос, dead-letter очередь и идемпотентный обработчик.
Коротко: callback ускоряет доставку результата, но не гарантирует её. Резервный опрос
res.php— обязательная часть архитектуры, а не подстраховка «на всякий случай».
Где обратный вызов может сломаться
Четыре типичных сценария, в которых результат не доходит до вашего обработчика:
- Сервер обработчика недоступен — CaptchaAI видит отказ в соединении (connection refused), результат не доставлен.
- Обработчик возвращает 5xx — CaptchaAI получает ответ с ошибкой; повтор не гарантирован и зависит от реализации на стороне CaptchaAI.
- Истёк тайм-аут сети — соединение зависает, решение может быть потеряно.
- Обработчик падает при записи результата — запрос принят, но результат не сохранён; решение «тихо» пропадает.
Отсюда практический вывод: никогда не полагайтесь только на callback. Он должен быть основным, но не единственным каналом доставки результата.
Схема 1: callback + резервный опрос res.php
Самая надёжная схема — принимать callback как основной канал, но параллельно отслеживать задачи, которые не получили callback за отведённое время, и после тайм-аута забирать результат опросом res.php. Ниже — рабочая реализация: при отправке задачи сохраняется её id, callback-хендлер закрывает задачу при получении результата, а фоновый поток каждые 30 секунд проверяет, не «зависли» ли какие-то задачи дольше 120 секунд.
Python
import os
import time
import threading
import requests
from flask import Flask, request
app = Flask(__name__)
API_KEY = os.environ["CAPTCHAAI_API_KEY"]
# Track task state
pending_tasks = {} # task_id -> {"submitted_at": timestamp, "status": "pending"}
results = {}
lock = threading.Lock()
def submit_captcha(sitekey, pageurl, callback_url):
"""Submit with callback, but track for fallback polling."""
resp = requests.post("https://ocr.captchaai.com/in.php", data={
"key": API_KEY,
"method": "userrecaptcha",
"googlekey": sitekey,
"pageurl": pageurl,
"pingback": callback_url,
"json": 1
})
data = resp.json()
if data.get("status") == 1:
task_id = data["request"]
with lock:
pending_tasks[task_id] = {
"submitted_at": time.time(),
"status": "pending"
}
return task_id
return None
@app.route("/callback")
def captcha_callback():
"""Primary result delivery — CaptchaAI sends results here."""
task_id = request.args.get("id")
solution = request.args.get("code")
with lock:
results[task_id] = solution
pending_tasks.pop(task_id, None)
return "OK", 200
def fallback_poller():
"""Poll for any tasks that missed their callback."""
while True:
time.sleep(30) # Check every 30 seconds
with lock:
stale_tasks = [
tid for tid, info in pending_tasks.items()
if time.time() - info["submitted_at"] > 120 # 2 min callback timeout
and info["status"] == "pending"
]
for task_id in stale_tasks:
resp = requests.get("https://ocr.captchaai.com/res.php", params={
"key": API_KEY,
"action": "get",
"id": task_id,
"json": 1
})
data = resp.json()
if data.get("status") == 1:
with lock:
results[task_id] = data["request"]
pending_tasks.pop(task_id, None)
print(f"Fallback poll recovered: {task_id}")
elif data.get("request") != "CAPCHA_NOT_READY":
# Permanent error — remove from pending
with lock:
pending_tasks.pop(task_id, None)
print(f"Task failed: {task_id} — {data.get('request')}")
# Start fallback poller in background
poller_thread = threading.Thread(target=fallback_poller, daemon=True)
poller_thread.start()
JavaScript
const express = require("express");
const axios = require("axios");
const app = express();
const API_KEY = process.env.CAPTCHAAI_API_KEY;
const pendingTasks = new Map(); // taskId -> { submittedAt, status }
const results = new Map();
async function submitCaptcha(sitekey, pageurl, callbackUrl) {
const resp = await axios.post("https://ocr.captchaai.com/in.php", null, {
params: {
key: API_KEY,
method: "userrecaptcha",
googlekey: sitekey,
pageurl: pageurl,
pingback: callbackUrl,
json: 1,
},
});
if (resp.data.status === 1) {
const taskId = resp.data.request;
pendingTasks.set(taskId, {
submittedAt: Date.now(),
status: "pending",
});
return taskId;
}
return null;
}
// Primary callback endpoint
app.get("/callback", (req, res) => {
const taskId = req.query.id;
const solution = req.query.code;
results.set(taskId, solution);
pendingTasks.delete(taskId);
res.sendStatus(200);
});
// Fallback poller
setInterval(async () => {
const now = Date.now();
const staleTasks = [];
for (const [taskId, info] of pendingTasks) {
if (now - info.submittedAt > 120000 && info.status === "pending") {
staleTasks.push(taskId);
}
}
for (const taskId of staleTasks) {
try {
const resp = await axios.get("https://ocr.captchaai.com/res.php", {
params: { key: API_KEY, action: "get", id: taskId, json: 1 },
});
if (resp.data.status === 1) {
results.set(taskId, resp.data.request);
pendingTasks.delete(taskId);
console.log(`Fallback recovered: ${taskId}`);
} else if (resp.data.request !== "CAPCHA_NOT_READY") {
pendingTasks.delete(taskId);
console.log(`Task failed: ${taskId} — ${resp.data.request}`);
}
} catch (err) {
console.error(`Poll error for ${taskId}: ${err.message}`);
}
}
}, 30000);
app.listen(3000);
Схема 2: dead-letter очередь для сбоев обработки
Приём callback может пройти успешно, а дальнейшая обработка — сломаться: недоступна база данных, не прошла валидация. CaptchaAI в этом случае уже получил свой 200 OK и повторно доставлять результат не будет — вся ответственность за сохранность данных на этом шаге на вашей стороне. Поэтому вместо того, чтобы терять результат при сбое, откладывайте его в dead-letter очередь и разбирайте отдельным процессом.
Python
import json
import os
import time
from pathlib import Path
DEAD_LETTER_DIR = Path("dead_letter")
DEAD_LETTER_DIR.mkdir(exist_ok=True)
@app.route("/callback")
def captcha_callback_with_dlq():
task_id = request.args.get("id")
solution = request.args.get("code")
try:
# Attempt normal processing
store_result(task_id, solution)
return "OK", 200
except Exception as e:
# Processing failed — save to dead-letter queue
dead_letter = {
"task_id": task_id,
"solution": solution,
"error": str(e),
"received_at": time.time()
}
dlq_path = DEAD_LETTER_DIR / f"{task_id}.json"
dlq_path.write_text(json.dumps(dead_letter))
print(f"DLQ: {task_id} — {e}")
return "OK", 200 # Still return 200 to CaptchaAI
def reprocess_dead_letters():
"""Retry processing dead-letter items."""
for dlq_file in DEAD_LETTER_DIR.glob("*.json"):
item = json.loads(dlq_file.read_text())
try:
store_result(item["task_id"], item["solution"])
dlq_file.unlink() # Remove after successful processing
print(f"DLQ reprocessed: {item['task_id']}")
except Exception:
pass # Leave in DLQ for next retry
JavaScript
const fs = require("fs");
const path = require("path");
const DLQ_DIR = path.join(__dirname, "dead_letter");
if (!fs.existsSync(DLQ_DIR)) fs.mkdirSync(DLQ_DIR);
app.get("/callback-dlq", (req, res) => {
const taskId = req.query.id;
const solution = req.query.code;
try {
storeResult(taskId, solution);
res.sendStatus(200);
} catch (err) {
// Save to dead-letter queue
const deadLetter = {
task_id: taskId,
solution: solution,
error: err.message,
received_at: Date.now(),
};
fs.writeFileSync(
path.join(DLQ_DIR, `${taskId}.json`),
JSON.stringify(deadLetter)
);
console.log(`DLQ: ${taskId} — ${err.message}`);
res.sendStatus(200); // Still acknowledge to CaptchaAI
}
});
function reprocessDeadLetters() {
const files = fs.readdirSync(DLQ_DIR).filter((f) => f.endsWith(".json"));
for (const file of files) {
const filePath = path.join(DLQ_DIR, file);
const item = JSON.parse(fs.readFileSync(filePath, "utf8"));
try {
storeResult(item.task_id, item.solution);
fs.unlinkSync(filePath);
console.log(`DLQ reprocessed: ${item.task_id}`);
} catch (err) {
// Leave in DLQ
}
}
}
// Retry DLQ every 5 minutes
setInterval(reprocessDeadLetters, 300000);
Схема 3: идемпотентный обработчик callback
CaptchaAI может доставить один и тот же callback дважды — например, при собственных сетевых ретраях. Обработчик обязан безопасно принимать повторную доставку одного id: не перезаписывать уже сохранённый результат и не выполнять побочные действия (запись в БД, списание баланса) во второй раз:
@app.route("/callback")
def idempotent_callback():
task_id = request.args.get("id")
solution = request.args.get("code")
with lock:
# Only process if not already handled
if task_id in results:
return "OK", 200 # Already processed — skip silently
results[task_id] = solution
pending_tasks.pop(task_id, None)
return "OK", 200
Какую схему выбрать
Единой «правильной» схемы нет — выбор зависит от объёма задач и того, что именно может отказать в вашей инфраструктуре:
- Небольшой объём задач, простои сервера редки — достаточно callback + резервного опроса.
- Высокий объём, возможны сбои базы данных при записи результата — добавляйте dead-letter очередь.
- Несколько обработчиков могут получить один и тот же callback — обработчик обязан быть идемпотентным.
- Продакшен с жёсткими SLA — используйте все три схемы вместе, они не исключают друг друга.
Поиск и устранение неисправностей
- Резервный опрос находит уже доставленные задачи — причина: гонка между callback и опросом. Решение: добавьте проверку идемпотентности, пропускайте задачу, если результат уже есть.
- Dead-letter очередь растёт, но не разбирается — причина: reprocessor не запущен или падает. Решение: проверьте логи reprocessor'а, убедитесь, что первопричина (например, БД) устранена.
- Callback вернул 200, но результат потерян — причина: обработчик падает уже после отправки ответа. Решение: сохраняйте результат до ответа 200 либо используйте dead-letter очередь.
- Слишком много запросов резервного опроса — причина: слишком много «зависших» задач. Решение: увеличьте тайм-аут ожидания callback, проверьте аптайм своего сервера.
Большинство «пропавших» решений на практике — это гонка между callback и резервным опросом, а не реальная потеря токена. Идемпотентная проверка перед записью результата закрывает эту причину полностью.
Частые вопросы
Как отличить временный сбой от постоянной ошибки при опросе res.php?
Ответ CAPCHA_NOT_READY в поле request означает «решение ещё не готово» — это не ошибка, опрос нужно продолжать. Любой другой текст в request при status: 0 — финальный статус: повторный опрос той же задачи результата не изменит, нужно создавать новую задачу.
Всегда ли нужно отвечать 200 OK на callback CaptchaAI, даже если обработка внутри упала?
Да. Код ошибки (4xx/5xx) ничего не даёт — CaptchaAI не гарантирует повторную доставку callback при таком ответе. Принимайте запрос с 200 OK сразу, а сбои обработки закрывайте на своей стороне через dead-letter очередь.
Сколько раз разумно повторять опрос res.php, прежде чем считать задачу потерянной?
Жёсткого лимита у API нет, но на практике достаточно опрашивать раз в 5–10 секунд и прекращать попытки через 2–3 минуты после отправки. Если к этому моменту задача не закрылась ни через callback, ни через опрос, дешевле пересоздать её, чем ждать дальше.
Что писать в dead-letter очередь, чтобы не нарушить требования к персональным данным?
Храните в записи id задачи, код ошибки и служебные метаданные — не сохраняйте туда исходные данные пользовательской сессии без необходимости. Это разумная гигиена логирования независимо от того, ориентируетесь вы на 152-ФЗ «О персональных данных» для аудитории в РФ или на GDPR-требования для остальных рынков.
Через сколько секунд после отправки задачи запускать резервный опрос?
Не раньше чем через 120 секунд. Большинство типов CAPTCHA решаются заметно быстрее, но 120 секунд с запасом покрывают и время решения, и сетевую задержку доставки самого callback — раньше опрашивать смысла нет.
