Captcha API error codes

All solve responses include errorId. When errorId is 1, read errorCode and errorDescription. Auth and balance errors use standard HTTP status codes.

Solve Error Shape

json

{
  "errorId":          1,
  "errorCode":        "ERROR_CAPTCHA_UNSOLVABLE",
  "errorDescription": "Unable to solve the captcha. The site may use advanced protection.",
  "taskId":           "scrx_1748350341234_ab12cd34"
}

Solve Error Codes

errorCodeFaultWhen it occurs

ERROR_CAPTCHA_UNSOLVABLEsolverChallenge answers submitted but rejected by PopularCaptcha — site may have changed protection type. Retry.

ERROR_INTERNALinternalRate limit on solver IP, PopularCaptcha protocol degradation, or other temporary infrastructure issue. Retry shortly.

ERROR_NOPECHAinternalNopeCha AI solver returned an API error (key invalid, quota exceeded). Reported to Scarnox — no action needed.

ERROR_CAPTCHA_TIMEOUTinternalSolve attempt exceeded 180s — solver was overloaded. Retry.

ERROR_NO_SLOT_AVAILABLEinternalAll solver workers are busy. Retry in a few seconds.

ERROR_INVALID_TASKTYPEusercaptcha_type not recognised. Must be PopularCaptchaTokenProxyless.

ERROR_SOLVER_UNAVAILABLEinternalSolver infrastructure not configured. Contact support if persistent.

HTTP Error Codes

These are returned as HTTP errors with a detail field — handle with catch/except blocks.

HTTPMeaning

401Missing or invalid API key — check Authorization header

402Insufficient balance — add credits in the dashboard

422Request body validation error — check field names and types

503Solver infrastructure not configured — contact support

Retry Strategy

python

import requests, time

# Errors safe to retry — all temporary internal issues
RETRYABLE = {
    "ERROR_NO_SLOT_AVAILABLE",
    "ERROR_INTERNAL",
    "ERROR_CAPTCHA_TIMEOUT",
}

# Errors that are permanent — don't retry
PERMANENT = {
    "ERROR_INVALID_TASKTYPE",   # fix captcha_type
    "ERROR_SOLVER_UNAVAILABLE", # contact support
}

def solve_with_retry(payload, retries=3):
    for attempt in range(retries):
        resp = requests.post(
            "https://api.scarnox.com/api/tasks/create",
            headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
            json=payload, timeout=185,
        )
        data = resp.json()
        if data.get("errorId") == 0:
            return data["solution"]["token"]
        code = data.get("errorCode", "UNKNOWN")
        desc = data.get("errorDescription", "")
        if code in PERMANENT:
            raise RuntimeError(f"[{code}] {desc}")   # don't retry
        if code in RETRYABLE:
            time.sleep(5 * (attempt + 1))
            continue
        # ERROR_CAPTCHA_UNSOLVABLE / ERROR_NOPECHA — retry once, then give up
        if attempt < 1:
            time.sleep(3)
            continue
        raise RuntimeError(f"[{code}] {desc}")
    raise RuntimeError("Max retries exceeded")

PreviousBalance