capi.Errors and retries
API response codes and what to check when a scenario fails.
Key or balance
If access is denied, check the key with /key. After /rotate, update the plugin setting. If the available balance is too low, top up the account.
Images and task type
Check the captcha type, all required images and that they belong to one round. GeeTest Icon needs three hints, Slide — the puzzle fragment, Nine — the current task's hint.
Clicks do not match the picture
Check the scale, the widget's position and that no windows overlap it. After the captcha refreshes, start over with the new round's data.
Session and proxy
Keep the browser session and proxy until the task is finished. After a network failure, check the task state in the plugin and the dashboard history before repeating the whole scenario.
API response codes
Every API error is returned as a JSON object: number is the error number, code its code, detail the server message, hint a short piece of advice; errors tied to a task also have task_id (also in the X-Task-Id header). The number and the code do not change: rely on them, not on the detail text.
A solve refusal (4001 unsolvable_image, HTTP 422) is not a server fault: detail says at which step the solver stopped and what it saw. The reserve for such a task is released. Keep the images you sent: they are a sample for training the model.
Retry a network failure with the same Idempotency-Key and the same body: an already issued solution is returned without another charge.
| Number | Code | HTTP | Meaning | What to do |
|---|---|---|---|---|
| 1001 | unauthorized | 401 | The API key is wrong or revoked, or the account is blocked. | Check the key with /key; after /rotate update the plugin setting. |
| 1002 | blocked | 403 | The account is blocked. | Contact the administrator. |
| 1003 | forbidden | 403 | Access to the resource is denied for this account. | Check the account permissions. |
| 1010 | plugin_signature_required | 403 | The plugin signature headers X-Capi-* are missing or malformed. | Update the plugin; do not send X-Capi-* headers in direct requests. |
| 1011 | plugin_request_expired | 403 | The time of the signed plugin request is outside the allowed window (120 s). | Check the computer clock and retry. |
| 1012 | plugin_version_not_permitted | 403 | This plugin version is disabled. | Download the current version from the downloads page. |
| 1013 | plugin_signature_invalid | 403 | The plugin signature does not match the one the server computed. | Check that the plugin has your API key and update it. |
| 1014 | plugin_replay | 409 | A plugin request with this nonce was already accepted. | Send a new request instead of resending the old one. |
| 1015 | report_salt_required | 403 | The report has no report_salt from the solve response. | Send the report_salt received in the response to the task. |
| 1016 | invalid_report_proof | 403 | The report_salt does not belong to this task. | Use the report_salt from the response to this very task. |
| 2001 | insufficient_balance | 402 | The available balance is lower than the task price. | Top up the balance. |
| 2002 | price_unavailable | 503 | No tariff is set for this captcha type. | Retry later or contact the administrator. |
| 2003 | rate_limit | 429 | The account created more tasks in a minute than allowed. | Wait a minute and retry. |
| 2004 | too_many_pending | 429 | Too many tasks without a report. | Send /v1/report for the finished tasks. |
| 2005 | report_expired | 409 | The report deadline of the task has passed. | Send the report right after the captcha provider check. |
| 2006 | not_solved | 409 | The task has no solution: the solve failed. | No report is needed for such a task. |
| 2007 | idempotency_conflict | 409 | The Idempotency-Key or operation ID was already used with a different body. | Use a new key for a new request; resend the same body for a network retry. |
| 2008 | request_pending_or_failed | 409 | The task with this Idempotency-Key is still running or has failed. | Check /v1/task/{task_id} or send the request with a new key. |
| 3001 | invalid_request | 422 | The request parameters failed validation. | Compare the parameters with the route description. |
| 3002 | invalid_json | 400 | The body is not JSON of the expected shape. | Send a JSON object, e.g. {"image": "<base64>"}. |
| 3003 | invalid_image | 400 | The image is empty or not a valid base64 string. | Send the whole image as base64. |
| 3004 | payload_too_large | 413 | The image or the request body is over the limit. | Shrink the image or drop extra data. |
| 3005 | captcha_type_required | 400 | The captcha type is not set. | Set it in the path /v1/solve/{type} or in the captcha_type parameter. |
| 3006 | unknown_captcha_type | 404 | There is no such captcha type. | Take the type from the list in detail or from the docs. |
| 3007 | invalid_variant | 400 | The model or type value is not an available one. | Pick a value from the list in detail. |
| 3008 | invalid_report | 400 | The report has no task_id or its result is not an allowed one. | Send {"task_id": ..., "result": "success|fail|continue"}. |
| 3009 | invalid_request_key | 400 | The Idempotency-Key must be 1 to 128 characters long. | Use a UUID. |
| 3010 | not_found | 404 | The task or resource is not found or belongs to another account. | Check the identifier. |
| 3011 | invalid_result | 400 | The report result is not success, fail or continue. | Send one of the three results. |
| 3012 | method_not_allowed | 405 | The route does not support this HTTP method. | Check the method in the route description. |
| 3013 | bad_request | 400 | The request is invalid. | Read detail. |
| 3014 | conflict | 409 | The state of the resource does not allow the operation. | Read detail. |
| 4001 | unsolvable_image | 422 | The images were read but the solver has no answer for them. detail names the step and what the solver saw. The reserve is released. | Keep the images you sent as a dataset sample and request a new captcha round. |
| 4002 | solver_busy | 429 | All solving slots are busy. | Retry in a second (Retry-After header). |
| 4003 | inference_failed | 500 | The solver failed. The reserve is released. | Retry; if it persists, send the task ID. |
| 4004 | inference_timeout | 504 | Solving did not finish in time. The reserve is released. | Retry the request. |
| 5000 | internal_error | 500 | Internal server error. | Retry later; if it persists, send the request time. |
| 5001 | database_unavailable | 503 | The database is unavailable. | Retry later. |
| 5002 | plugin_config_unavailable | 503 | The plugin configuration on the server is unavailable. | Retry later. |
| 5003 | journal_unavailable | 503 | The task journal is not configured on the server. | Contact the administrator. |
| 5004 | billing_disabled | 503 | Billing is disabled on the server. | Contact the administrator. |
| 5005 | service_unavailable | 503 | The service is temporarily unavailable. | Retry later. |
Data for troubleshooting
Keep the plugin version, captcha type, task ID, time and error message. Do not publish your API key, proxy passwords or cookies.