Limits and best practices
Rate limits, parallel tasks, polling interval, retries and how long tokens and results live.
Цей розділ показано англійською.
Limits#
| What | Limit | Answer above it |
|---|---|---|
createTask per key | 30/s, bursts up to 60 | ERROR_TOO_MUCH_REQUESTS (91) |
getTaskResult per key | 50/s | ERROR_TOO_MUCH_REQUESTS (91) |
| All requests from one IP | 100/s, bursts up to 200 | ERROR_TOO_MUCH_REQUESTS (91) |
| Tasks in progress per key | 200 (configurable per key) | ERROR_NO_SLOT_AVAILABLE (2) |
| Spending per key | daily and monthly caps you set | ERROR_SPENDING_LIMIT (92) |
| Request body | 1 MiB | ERROR_TASK_ABSENT (22) |
| Waiting for a worker | 180 s | ERROR_RECAPTCHA_TIMEOUT (30), not charged |
| Result storage | 10 min after it is ready | ERROR_NO_SUCH_CAPCHA_ID (16) |
| Refund reports | 24 h after solving | recorded without a refund |
| Webhook delivery | 3 attempts, 5 s each | — |
These are the current platform defaults. Need more? Write to support.
Polling interval#
- Poll each task every 2–3 seconds. Polling more often does not make solving faster.
- Stop at
readyor at the first error. - Give up after about 5 minutes: by then every task is either solved or failed.
- Many tasks at once? Use webhooks instead of polling.
Parallel tasks#
- Tasks are independent: run them in parallel up to the key's limit (200 by default).
- On
ERROR_NO_SLOT_AVAILABLE, wait for some tasks to finish and retry in 1–2 seconds. - Keep
createTaskunder 30 per second per key: spread bursts over time. - Use separate keys for separate projects: limits, caps and statistics are per key.
Retries#
| Errors | What to do |
|---|---|
ERROR_TOO_MUCH_REQUESTS, ERROR_NO_SLOT_AVAILABLE, ERROR_INTERNAL, network errors | retry the same request with a growing pause: 1, 2, 4… seconds |
ERROR_CAPTCHA_UNSOLVABLE, ERROR_RECAPTCHA_TIMEOUT, proxy errors | create a new task — the failed one is free |
ERROR_KEY_DOES_NOT_EXIST, ERROR_ZERO_BALANCE, ERROR_TASK_ABSENT, ERROR_TASK_NOT_SUPPORTED, ERROR_IP_NOT_ALLOWED, ERROR_SPENDING_LIMIT | do not retry: fix the cause first |
A repeated getTaskResult is always safe. A repeated createTask creates another task.
Token lifetime#
- A reCAPTCHA token is valid for about 2 minutes and only once. Create the task right before you need the token.
- The API keeps the result for 10 minutes, but Google rejects an old token much earlier.
- The site rejected the token? Report it and get the money back.
HTTP timeouts#
Use a timeout of about 30 seconds for API calls. Every answer comes at once — solving never blocks a request.