Home›API

Task lifecycle

How a task goes from creation to result, and what happens to your money at each stage.

Diagram: the path of a task and what happens to the money

#Statuses

status	meaning	money
`processing`	the task has been accepted and is being solved	the cost is reserved
`ready`	the solution is ready, the token is in `solution`	stays charged
error `ERROR_CAPTCHA_UNSOLVABLE`	the task could not be solved or timed out	the cost is refunded

The createTask method checks the request in order and stops at the first error. No task is created and nothing is charged before the balance check.

The key exists — otherwise ERROR_KEY_DOES_NOT_EXIST. A request body that is not valid JSON produces the same error.
The task type is supported — otherwise ERROR_TASK_NOT_SUPPORTED.
websiteURL and websiteKey are provided — otherwise ERROR_BAD_PARAMETERS.
The site is allowed — otherwise ERROR_SITE_NOT_SUPPORTED.
The key is not disabled, the balance has enough funds, and the task limit is not exceeded — otherwise ERROR_KEY_DISABLED, ERROR_ZERO_BALANCE or ERROR_NO_SLOT_AVAILABLE.
The task is submitted for solving — on failure, ERROR_SERVICE_UNAVAILABLE, and the cost is refunded.

stage	time
solving	usually 15–60 seconds
waiting for the result	up to 5 minutes, after which the task is closed with the error `ERROR_CAPTCHA_UNSOLVABLE`
using the token	60 seconds after the status becomes `ready`
task retention	5 minutes, after which `getTaskResult` returns `ERROR_NO_SUCH_CAPCHA_ID`

getTaskResult: poll every 2–3 seconds while the status is processing.
ERROR_CAPTCHA_UNSOLVABLE: get a new gid and create a new task. The old task cannot be retried.
ERROR_SERVICE_UNAVAILABLE: retry createTask after 5–30 seconds; you can keep the same parameters.
Do not repeat createTask "just in case" before you have received a response: every task you create reserves money and is counted as a separate task.