Безопасный scope: Это руководство применимо только к собственным или явно авторизованным QA-, staging- и production-средам. Описаны сценарии диагностики, тестирования и наблюдаемости вашей собственной CAPTCHA-интеграции — не для сторонних сайтов и не для несанкционированных workflow.
CAPTCHA-токены — g-recaptcha-response, Turnstile-token и им подобные — имеют ограниченный TTL. В собственном backend их можно безопасно кешировать только на время жизни и только в контексте оригинального запроса. Это руководство описывает корректную работу с кешем и идемпотентными ретраями.
TTL по провайдерам
| Провайдер | Ориентировочный TTL | Особенности |
|---|---|---|
| reCAPTCHA v2 | около 120 с | один токен на действие |
| reCAPTCHA v3 | около 120 с | имя action имеет значение |
| Cloudflare Turnstile | до 5 мин | токен одноразовый |
| hCaptcha | около 120 с | токен одноразовый |
Точные значения уточняйте в документации провайдера.
Когда переиспользование уместно
- идемпотентные повторы того же самого запроса в пределах TTL;
- безопасный retry после кратковременной сетевой ошибки;
- транзакционная запись с retry на уровне backend.
Переиспользование между разными пользователями или между разными действиями недопустимо.
Минимальный кеш в собственном backend
import time
_cache = {}
TTL = 110
def remember(key: str, token: str) -> None:
_cache[key] = (token, time.time() + TTL)
def get(key: str) -> str | None:
item = _cache.get(key)
if not item:
return None
token, expires = item
if time.time() >= expires:
_cache.pop(key, None)
return None
return token
Идемпотентные retries
Передавайте Idempotency-Key вместе с токеном. Если backend получает тот же ключ — он использует уже валидированный токен и не запрашивает новый у CaptchaAI.
Логи и наблюдаемость
Структурированные логи помогают сравнивать поведение CAPTCHA между релизами и быстро находить регрессии в собственных формах:
import json, time, logging
log = logging.getLogger('captcha-qa')
def record(event: str, **fields) -> None:
payload = {'ts': time.time(), 'event': event, **fields}
log.info(json.dumps(payload, ensure_ascii=False))
Минимальный набор полей для каждой попытки: slug, captcha_type, task_id, wait_seconds, verify_status, env. Этого достаточно, чтобы построить дашборд медианы / P90 / P99 по типу CAPTCHA и по среде.
Troubleshooting
| Симптом | Что сделать |
|---|---|
| Токен невалиден на ретрае | Уменьшите TTL в кеше |
| Двойные списания | Проверьте идемпотентный ключ |
| Кеш растёт неограниченно | Включите expiry-cleanup |
| Coldstart очищает кеш | Используйте Redis с TTL |
QA-чек-лист
- Запрос отправляется только на собственные или авторизованные endpoints.
- Тестовые учётные записи, события и платежи помечены как фиктивные.
- CAPTCHA-токен проверяется на собственном backend, а не доверяется клиенту.
- Логи содержат
task_id, тип CAPTCHA, время ожидания и pass/fail. - Скрипт возвращает корректный exit code, чтобы CI мог принять решение.
FAQ
Можно ли использовать этот подход на сторонних сайтах?
Нет. Описанные сценарии применимы только к собственным или явно авторизованным средам. Для чужих ресурсов запрашивайте письменное разрешение владельца.
Что делать, если CaptchaAI вернул ошибку?
Логируйте task_id, тип CAPTCHA и текст ошибки, повторите запрос с экспоненциальной задержкой и фиксируйте долю ошибок в дашборде. Постоянный рост ошибок — повод проверить sitekey и страницу.
Как сравнивать результаты между релизами?
Сохраняйте логи в одном формате и стройте отчёт по медиане, P90 и P99 на одинаковом наборе сценариев. Сравнивайте только сопоставимые выборки в собственной среде.
Безопасные связанные руководства
- Быстрый старт CaptchaAI
- QA-тестирование CAPTCHA в авторизованных средах
- Тестирование CAPTCHA API на собственных формах
- Отладка: браузерный тест падает, API проходит
- reCAPTCHA v2 через API
- Cloudflare Turnstile через API
- GeeTest v3 через API
Эффективное использование CAPTCHA-токенов в собственном backend — подключите CaptchaAI.
