Recover a timed-out request without paying for another task

A requestId identifies one logical task across creation attempts. It accepts 1–64 ASCII letters, numbers, underscores, or hyphens. Choose it before sending the request and keep it with the original task inputs.

1. 1.

   Save the task body

   Put the complete request, including requestId, in request.json. For reCAPTCHA Enterprise, include site as a hostname, action, and exactly one of proxy or proxyCandidates. Don’t add type or url. Keep the file private because it contains proxy credentials.

2. 2.

   Send the saved file

   Run the command below with your workspace API key. Keep the key on the server.

3. 3.

   If the connection times out, repeat the command

   Use the identical command and unchanged request.json. Don’t generate another requestId or edit the task inputs just because the response didn’t arrive.

# request.json contains one valid task body and a saved requestId.
# Keep the file private: it contains your proxy credentials.
curl --fail-with-body --max-time 30 \
  'https://api.solvethree.com/v1/tasks?waitMs=0' \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY" \
  -H 'Content-Type: application/json' --data-binary @request.json

# If the connection broke, run the identical command with the identical file.
# New task: HTTP 201. Same requestId + same inputs: HTTP 200, existing task.
# Same requestId + changed inputs: HTTP 409.

HTTP 201 means a new task was created. HTTP 200 means the identical request recovered the existing task. Read the returned task ID and status in either case; neither HTTP status alone means a solution is ready.

For a concrete changed-input example, suppose the saved request has action set to login. Changing it to checkout while keeping the same requestId returns HTTP 409, a request ID conflict. To recover the original task, restore the original file and replay it. If you intentionally need the changed inputs, give that new logical task a new requestId.

Handle non-success HTTP responses before reading a task success payload. A 409 is an HTTP request error, not a terminal failure of the original task.

Both official SDKs generate a requestId when you omit it, but neither automatically retries task creation. If an SDK call throws, inspect its recovery fields before starting another task.

• JavaScript: SolvethreeError exposes requestId and taskId.
• Python: SolvethreeError exposes request_id and task_id.

If the error contains a task ID, resume GET polling for that task; there’s no need to repeat creation. If it contains only a request ID, replay creation with that ID and the original inputs, then use the returned task ID. Keeping the original inputs matters even when the SDK generated the ID.

Don’t treat every exception as an interrupted creation. TaskFailedError represents a task that has already reached terminal failed status, not a request that needs recovery.

Retrieve the recovered task with GET /v1/tasks/:id. Continue polling while its status is pending or solving. Only ready contains a usable solution.

If the status is failed, stop polling and inspect errorCode and error. Failed solves are refunded. That is different from a website rejecting a generated solution: ready means the solution is available, not that the target accepted it.

Completed results can return HTTP 410 after retention expires, so recovery isn’t permanent result storage. For the polling loop itself, see task polling and timeouts.