capi.Ошибки и повторы
Коды ответов API и что проверить при сбое сценария.
Ключ или баланс
При отказе в доступе проверьте ключ командой /key. После /rotate обновите настройку плагина. При нехватке доступного баланса пополните аккаунт.
Изображения и тип задания
Проверьте тип капчи, все необходимые изображения и их соответствие одному раунду. Для GeeTest Icon нужны три подсказки, для Slide — фрагмент пазла, для Nine — подсказка текущего задания.
Клики не совпадают с картинкой
Проверьте масштаб, положение виджета и отсутствие перекрывающих окон. После обновления капчи начните работу с данными нового раунда.
Сессия и прокси
Сохраняйте браузерную сессию и прокси до завершения задания. При сетевом сбое проверяйте состояние задачи через плагин и историю в кабинете, прежде чем повторять весь сценарий.
Коды ответов API
Каждая ошибка API возвращается JSON-объектом: number — номер ошибки, code — её код, detail — сообщение сервера, hint — короткий совет; у ошибок, связанных с задачей, есть ещё task_id (он же в заголовке X-Task-Id). Номер и код не меняются — ориентируйтесь на них, а не на текст detail.
Отказ распознавания (4001 unsolvable_image, HTTP 422) — не сбой сервера: в detail указано, на каком шаге решатель остановился и что он увидел. Резерв по такой задаче освобождён. Сохраните отправленные картинки: это пример для обучения модели.
Сетевой повтор отправляйте с тем же Idempotency-Key и тем же телом: уже выданное решение вернётся без повторного списания.
| Номер | Код | HTTP | Что значит | Что делать |
|---|---|---|---|---|
| 1001 | unauthorized | 401 | Ключ неверен, отозван или аккаунт заблокирован. | Проверьте ключ командой /key; после /rotate обновите настройку плагина. |
| 1002 | blocked | 403 | Аккаунт заблокирован. | Обратитесь к администратору. |
| 1003 | forbidden | 403 | Доступ к ресурсу запрещён для этого аккаунта. | Проверьте права аккаунта. |
| 1010 | plugin_signature_required | 403 | Заголовки подписи плагина X-Capi-* отсутствуют или имеют неверный формат. | Обновите плагин; в прямом запросе не отправляйте заголовки X-Capi-*. |
| 1011 | plugin_request_expired | 403 | Время подписанного запроса плагина вышло за допустимое окно (120 с). | Проверьте часы компьютера и повторите запрос. |
| 1012 | plugin_version_not_permitted | 403 | Версия плагина отключена. | Скачайте актуальную версию на странице загрузок. |
| 1013 | plugin_signature_invalid | 403 | Подпись плагина не совпала с подписью сервера. | Проверьте, что в плагине указан ваш API key, и обновите плагин. |
| 1014 | plugin_replay | 409 | Запрос плагина с таким nonce уже принят. | Отправьте новый запрос, не пересылая старый. |
| 1015 | report_salt_required | 403 | В отчёте нет report_salt из ответа на решение. | Передайте report_salt, полученный в ответе на задачу. |
| 1016 | invalid_report_proof | 403 | report_salt не подходит к этой задаче. | Используйте report_salt из ответа именно на эту задачу. |
| 2001 | insufficient_balance | 402 | Доступного баланса меньше цены задачи. | Пополните баланс. |
| 2002 | price_unavailable | 503 | Для этого типа капчи не задан тариф. | Повторите позже или напишите администратору. |
| 2003 | rate_limit | 429 | За минуту создано больше задач, чем разрешено аккаунту. | Подождите минуту и повторите. |
| 2004 | too_many_pending | 429 | Слишком много задач без отчёта. | Отправьте /v1/report по выполненным задачам. |
| 2005 | report_expired | 409 | Срок отчёта по задаче истёк. | Отправляйте отчёт сразу после проверки у провайдера капчи. |
| 2006 | not_solved | 409 | У задачи нет решения: распознавание завершилось ошибкой. | Отчёт по такой задаче не нужен. |
| 2007 | idempotency_conflict | 409 | Idempotency-Key или ID операции уже использован с другим телом. | Для нового запроса берите новый ключ; для сетевого повтора отправляйте то же тело. |
| 2008 | request_pending_or_failed | 409 | Задача с этим Idempotency-Key ещё выполняется или завершилась ошибкой. | Проверьте состояние в /v1/task/{task_id} или отправьте запрос с новым ключом. |
| 3001 | invalid_request | 422 | Параметры запроса не прошли проверку. | Сверьте параметры с описанием маршрута. |
| 3002 | invalid_json | 400 | Тело запроса не разобрано как JSON нужной формы. | Отправьте JSON-объект, например {"image": "<base64>"}. |
| 3003 | invalid_image | 400 | Изображение пустое или не является корректной строкой base64. | Передайте целую картинку в base64. |
| 3004 | payload_too_large | 413 | Картинка или тело запроса больше лимита. | Уменьшите картинку или не присылайте лишнего. |
| 3005 | captcha_type_required | 400 | Не указан тип капчи. | Укажите тип в пути /v1/solve/{type} или в параметре captcha_type. |
| 3006 | unknown_captcha_type | 404 | Такого типа капчи нет. | Возьмите тип из списка в detail или из документации. |
| 3007 | invalid_variant | 400 | Значение параметра model или type не из доступных. | Выберите значение из списка в detail. |
| 3008 | invalid_report | 400 | В отчёте нет task_id или result не из допустимых. | Отправьте {"task_id": ..., "result": "success|fail|continue"}. |
| 3009 | invalid_request_key | 400 | Idempotency-Key должен содержать от 1 до 128 символов. | Используйте UUID. |
| 3010 | not_found | 404 | Задача или ресурс не найдены либо принадлежат другому аккаунту. | Проверьте идентификатор. |
| 3011 | invalid_result | 400 | Результат отчёта не success, fail или continue. | Передайте один из трёх результатов. |
| 3012 | method_not_allowed | 405 | Для маршрута не поддерживается этот HTTP-метод. | Проверьте метод в описании маршрута. |
| 3013 | bad_request | 400 | Запрос неверен. | Прочитайте detail. |
| 3014 | conflict | 409 | Состояние ресурса не позволяет операцию. | Прочитайте detail. |
| 4001 | unsolvable_image | 422 | Картинки приняты, но решения для них нет. В detail указано, на каком шаге и что увидел решатель. Резерв освобождён. | Сохраните отправленные картинки как пример для датасета и запросите новый раунд капчи. |
| 4002 | solver_busy | 429 | Все слоты распознавания заняты. | Повторите через секунду (заголовок Retry-After). |
| 4003 | inference_failed | 500 | Решатель завершился ошибкой. Резерв освобождён. | Повторите запрос; если ошибка остаётся, передайте ID задачи. |
| 4004 | inference_timeout | 504 | Распознавание не уложилось в отведённое время. Резерв освобождён. | Повторите запрос. |
| 5000 | internal_error | 500 | Внутренняя ошибка сервера. | Повторите позже; если ошибка остаётся, передайте время запроса. |
| 5001 | database_unavailable | 503 | База данных недоступна. | Повторите позже. |
| 5002 | plugin_config_unavailable | 503 | Настройки плагинов на сервере недоступны. | Повторите позже. |
| 5003 | journal_unavailable | 503 | Журнал задач не настроен на сервере. | Обратитесь к администратору. |
| 5004 | billing_disabled | 503 | Биллинг на сервере выключен. | Обратитесь к администратору. |
| 5005 | service_unavailable | 503 | Сервис временно недоступен. | Повторите позже. |
Данные для разбора
Сохраните версию плагина, тип капчи, ID задачи, время и сообщение об ошибке. Не публикуйте API key, пароли прокси и cookies.