Error Handling

Every endpoint returns the same envelope. Branch on errorId, surface errorCode to logs, and use errorDescription for human-readable messages.

Error response

{
    "errorId": 1,
    "errorCode": "CAPTCHA_UNSOLVABLE",
    "errorDescription": "The captcha could not be solved. Check your parameters or try again."
}

Error IDs

Full error code reference

Every code the API can return:

Retries and idempotency

createTask is not idempotent: every call charges the estimated cost up front. If your retry succeeds you get charged again, even if the original request also went through. Build retry logic accordingly:

• errorId === 2 (internal): safe to retry with exponential backoff. The estimated cost is refunded automatically.
• errorId === 1 and errorCode === "RATE_LIMITED": also safe to retry, with a small jittered delay. Refunded automatically.
• errorId === 1 for everything else (INVALID_TASK_DATA, ERROR_KEY_DOES_NOT_EXIST, etc.): fix the input first. Retrying without changes will fail the same way.

getTaskResult never charges and never mutates state, so retry it as often as you need.

Auto retry & fallback

Instead of building your own retry loop, let AnySolver recover inside a single task. Enable them per request with settings.retry and settings.fallback: auto retry re-tries the same provider, auto fallback moves to the next provider in the routing candidate list. See Routing Strategies for the full behavior.

A recovered task succeeds with errorId: 0; you are charged for the provider that ultimately solved it. With settings.statistics enabled, the retry object on getTaskResult lists every attempt and its error.

Which errors retry or fall back by default

When you omit onErrors, AnySolver uses a safe set of faults that another attempt can clear. It never includes user-input errors, so a misconfigured request is not retried into the same failure.

CAPTCHA_UNSOLVABLE means the provider failed a single solve, which usually succeeds on the next attempt, so it retries the same provider before falling back. Fallback's set adds PROVIDER_GLOBAL_LIMIT_REACHED, where the current provider is exhausted and only a different one can make progress. Override either list with onErrors to widen or narrow the trigger set. onErrors only accepts refundable provider-failure codes; any other code could never trigger another attempt, so it is rejected at validation instead of silently doing nothing.

Retry and fallback only apply to refundable failures, and you are billed once: the initial estimate is charged up front and adjusted to the final provider's price when the task finishes (charging the difference for a pricier provider, refunding it for a cheaper one, or refunding in full if every attempt fails refundably). A non-refundable failure is always terminal and keeps the charge, even if you list its code in onErrors.

Settings validation errors

Invalid settings fail fast with errorCode: "VALIDATION_ERROR" and a precise message. The most common:

Example handler

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function postWithRetry(url, body, attempt = 0) {
    const res = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(body),
    });
    const data = await res.json();

    if (data.errorId === 0) return data;

    // Internal errors: retry with exponential backoff (max 5 attempts).
    if (data.errorId === 2 && attempt < 5) {
        await sleep(2 ** attempt * 500);
        return postWithRetry(url, body, attempt + 1);
    }

    // External errors: surface to the caller. The caller decides whether to retry.
    throw Object.assign(new Error(data.errorDescription ?? data.errorCode), {
        errorId: data.errorId,
        errorCode: data.errorCode,
    });
}

Related