SurSolver
Docs menu

Guides

Docs / Guides

Task lifecycle

What happens between createTask and getTaskResult — statuses, how long answers stay, failures and what a failed task costs.

From submission to solution

  1. Accepted. POST /createTask validates the contract for task.type, runs the limits, and charges the task. The answer is {"errorId":0,"taskId":"tsk_…","status":"idle"} — the task exists and is queued.
  2. Solving. While the task is queued and while a solver works on it, POST /getTaskResult answers {"errorId":0,"status":"processing"}. A solve may be attempted more than once before it is reported; those internal attempts do not change the price of the task.
  3. Done. {"errorId":0,"status":"ready","solution":{…}} — the result is final and stays readable for the retention window. Each task type returns its own keys; they are listed in GET /v1/task-types.
  4. Failed. errorId: 1 with ERROR_FAILED (the solve failed or was cancelled), ERROR_TASK_TIMEOUT (execution took too long), or ERROR_TASK_EXPIRED (the retention window passed). A failed task cannot later become successful.

Execution time limits

A task has up to 60 seconds to begin processing and then up to 120 seconds to finish, by default. Retries or a service restart do not restart these limits. The combined budget can be about 180 seconds; this is not a 60-second total guarantee.

An execution timeout answers ERROR_TASK_TIMEOUT and returns the original payment or package solve once. It is separate from result retention. If the service is temporarily unavailable, the refund is recorded when recovery can run.

Retention

Results are kept for 30 minutes from task creation by default. After that window a task answers ERROR_TASK_EXPIRED and the result is gone — store what you need right away. Polling an unknown or another account’s taskId answers ERROR_TASK_NOT_FOUND; the two cases are indistinguishable on purpose.

Failure, retries and money

  • A task is charged when it is accepted. A task that finishes as failed, including expiry before completion, automatically returns its original charge or subscription solve once; see Billing & packages. A client polling deadline alone does not change a task’s status.
  • A failed task is final. To try again, submit a new task: createTask has no idempotency header, so a retried submission is a new, separately charged task.
  • Do not keep polling after the first errorId: 1. The answer will not change.

Polling politely

Poll every 3 seconds. Polling is not metered by the rate limits, but a task that is still processing will not finish sooner if you ask more often — you would only get more processing answers.