solvethree API errors: what to fix and when to retry

Handle non-success HTTP responses before reading a success payload. For POST /v1/tasks, 201 means a new task was created; 200 means an idempotent replay returned the existing task. Neither response means the solve has finished.

400 — invalid request body

Compare the submitted body with the documented fields and requirements for your task type.

Try this: Correct the input before submitting again. Retrying an unchanged invalid body won't fix it. Use the task creation contract to check the request.

401 — invalid API key

Check that the request includes Authorization: Bearer followed by a valid workspace API key.

Try this: Add the missing key or correct the rejected key. Keep it on the server rather than exposing it in browser code.

402 — insufficient credit

Check the workspace credit balance associated with the API key.

Try this: Add credit to that workspace before retrying. Don't treat unrelated HTTP errors or task failures as balance problems.

403 — inactive site profile

For reCAPTCHA, confirm that the target site has an active profile available to your workspace.

Try this: Set up the target site in the console and confirm the profile is active. Supplying a hostname and action in the task doesn't create a profile. This gateway response isn't evidence that the target website blocked you.

409 — request ID conflict

Check whether the same requestId was previously used with different task inputs.

Try this: Use the original inputs to recover the original task. If you intend to create a different task, give it a new request ID.

410 — stored result expired

Check whether you're retrieving a completed task whose stored result is no longer retained.

Try this: Stop fetching that result. Create a new solve if you still need one. This status describes API result retention, not the target token or cookie's lifetime.

429 — rate limited

Read the actual Retry-After response.

Try this: Wait as instructed before retrying and reduce the request rate. Don't keep polling or submitting at the same rate while throttled.

502 — generation service unavailable

Distinguish service unavailability from invalid input or insufficient credit.

Try this: Retry later. For another attempt at the same creation request, reuse its request ID and unchanged task inputs.

HTTP 503 means generation capacity is unavailable. Retry later; for the same creation request, reuse its request ID and unchanged task inputs.

• pending or solving: continue polling the existing task; don't create a replacement just because it isn't ready.
• ready: stop polling and read the solution.
• failed: stop polling and inspect errorCode and error.

{
  "id": "example_login_001",
  "status": "failed",
  "errorCode": "site-unreachable",
  "error": "target page did not respond"
}

Here, site-unreachable is a task error code, not an HTTP status. Check the submitted target URL and whether the page responds before requesting another solve. More polls won't restart this failed task, and replaying its original request ID returns the existing task rather than starting a replacement.

A connection timeout doesn't prove that task creation failed. Use an optional requestId before your first creation attempt so you can safely recover the same logical task. It must contain 1–64 ASCII letters, numbers, underscores, or hyphens.

1. 1.

   If you have the task ID, retrieve it

   Use GET /v1/tasks/:id and handle the HTTP response before checking the task status.

2. 2.

   If the creation response was lost, replay the original request

   Submit the same task inputs with the same request ID. Idempotent replay returns the existing task if it was created. Don't change inputs under that ID.

3. 3.

   Create a replacement only when you mean to start another solve

   A new request ID represents new work, not recovery of the previous request. Use it deliberately—for example, after investigating a terminal failure and deciding to try again.

See request ID recovery for replay handling, or polling and timeouts when creation succeeded but the task is still running.