Skip to content

api documentation

three endpoints, full code examples in 5 languages. integrate in under 60 seconds.

Quick Start

BASE_URL = "https://api.capzy.ai"

# 1. Create task
POST /createTask
# 2. Poll for result
POST /getTaskResult
# 3. Check balance
POST /getBalance

Endpoints

POST/createTaskCreate a new captcha solving task

Request

{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}

Response

{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultPoll for task result

Request

{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}

Response

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceCheck account balance

Request

{ "clientKey": "capzy_..." }

Response

{ "errorId": 0, "balance": 9.50 }
POST/reportScoreOptional: report Google's verified score back for V3 tasks. Powers your dashboard's V3 quality view. One report per task; reports must arrive within 24 hours of solve completion.

Request

{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}

Response

{ "errorId": 0 }

Supported Task Types

Loading…

Live list of currently-enabled task types, grouped by captcha provider. Pricing and average solve time auto-update from cluster telemetry.

Loading task types…

Rate Limits

Limits are enforced per account, aggregated across all API keys you own. Going over the limit returns an error code without consuming credits.

Tier
Concurrent Tasks
Rate Limit
Notes
Default
30
30 req/sec
Every new account starts here
Higher concurrent
300+
100+ req/sec
Open a support ticket with your expected volume — no separate price tier, same per-solve rate
Concurrent Tasks — how many tasks you can have in the solve queue at once. A task counts toward your limit from createTask until it finishes (success, failure, or timeout).

Rate Limit — how many createTask calls you can make per second. Sliding window, enforced per account. Exceeding the rate returns ERROR_RATE_LIMITED with no credits deducted.

Error Codes

Every error returned by /createTask / /getTaskResult with the fix. Failed solves auto-refund — credits return to your balance immediately.

Authentication

Issues with your API key or IP.
  • ERROR_KEY_DOES_NOT_EXIST#

    Your API key wasn't recognized.

    Fix: Double-check the value in Dashboard → API Keys. Keys start with `capzy_`. Rotated keys are invalidated immediately.

  • ERROR_IP_NOT_ALLOWED#

    Your request IP isn't on the API key's allowlist.

    Fix: Add your IP to the key's allowlist in Dashboard → API Keys, or remove the allowlist entirely if you don't need IP pinning.

  • ERROR_IP_BLOCKED#

    Your IP is temporarily banned for sending too many invalid requests.

    Fix: We ban IPs that send 100+ invalid requests in 10 minutes (escalating). Fix the bug causing invalid requests, then wait — bans auto-expire from 1 minute up to 24 hours depending on tier.

Validation

Bad task parameters or wrong type for the sitekey.
  • ERROR_INVALID_PARAMS#

    Request body was malformed or missing required fields.

    Fix: Check that `clientKey` is at the top level and `task` contains `type` plus the required identifier (websiteURL/websiteKey/captchaId/etc). See the Task Types section for the per-type required params.

  • ERROR_BAD_SITEKEY#

    The `websiteKey` isn't registered with any captcha provider we can identify.

    Fix: Make sure you're copying the full sitekey from the target page (look for `data-sitekey`, `sitekey:`, or the parameter in `grecaptcha.render` / `hcaptcha.render`).

  • ERROR_TASK_NOT_SUPPORTED#

    The task `type` you submitted isn't a captcha type Capzy currently supports.

    Fix: See the Task Types section below for the full enabled list. If you need a captcha not listed, open a ticket and we'll prioritize it.

  • ERROR_WRONG_TASK_TYPE#

    Task type doesn't match the sitekey's actual provider.

    Fix: We pre-flight-check sitekeys against their real provider. The error response includes a `recommended` field — switch to that task type. (No credit charged.)

  • ERROR_PROXY_REQUIRED#

    This captcha is IP-bound — its tokens are tied to the IP that solved them.

    Fix: Switch to the `*Task` variant (instead of `*TaskProxyLess`) and pass `proxyAddress` matching the IP you'll use to submit the token. Affects: Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.

  • ERROR_NO_PROXY#

    Proxy fields are required for this task type but were missing.

    Fix: Include `proxyType`, `proxyAddress`, `proxyPort` (and optionally `proxyLogin`/`proxyPassword`/`userAgent`) in your task body.

  • ERROR_PROXY_CONNECT_REFUSED#

    Your supplied proxy refused the connection.

    Fix: Check proxy credentials, host reachability, and that the IP is alive. Try the same proxy from your own machine first to isolate provider issues.

Rate Limits

Concurrent / per-second / refund-ratio caps.
  • ERROR_MAX_TASKS_REACHED#

    You've reached the concurrent-tasks cap for your account tier.

    Fix: Wait for in-flight tasks to finish before submitting more. Default Regular tier is 30 concurrent; contact support to upgrade.

  • ERROR_RATE_LIMITED#

    You're submitting /createTask faster than your rate limit.

    Fix: Slow down and retry. Default Regular tier is 30 req/sec sliding window. Exceeding the rate doesn't consume credits.

  • ERROR_NO_SLOT_AVAILABLE#

    Cluster capacity is temporarily saturated.

    Fix: Retry after a few seconds — this is transient. If it persists for minutes, check status.capzy.ai.

  • ERROR_REFUND_RATE_LIMIT#

    Your account's recent failure ratio is too high — likely misconfigured client.

    Fix: Stop the run and check your task params (sitekey, websiteURL, action). Once the failure rate drops below the threshold, requests resume automatically.

  • ERROR_SYSTEM_MAINTENANCE#

    Capzy is in scheduled maintenance.

    Fix: Retry after the maintenance window. We post advance notices on the status page.

Solve Outcomes

What the solver returned. Failed solves are auto-refunded.
  • ERROR_TIMEOUT#

    Task didn't complete within the per-type timeout cap.

    Fix: Auto-refunded — no charge. Most timeouts are transient. If a specific captcha consistently times out, open a ticket with the task UUID.

  • ERROR_CAPTCHA_UNSOLVABLE#

    Solver exhausted its retry budget on this challenge.

    Fix: Auto-refunded — no charge. Common causes: stale sitekey, websiteURL doesn't match the embedding domain, the captcha was disabled by the target site.

  • ERROR_NULL_RESULT#

    Solver finished but returned no token.

    Fix: Auto-refunded. Usually indicates the target site removed the captcha mid-solve. Retry; if it persists, open a ticket.

  • ERROR_INTERNAL#

    Unexpected error inside the solve pipeline.

    Fix: Auto-refunded. Retry — these are rare. If you see them in a tight loop, open a ticket with the task UUID.

  • ERROR_ZERO_BALANCE#

    Account balance too low to cover the task cost.

    Fix: Add credits from Dashboard → Billing. Failed solves are auto-refunded so you only pay for successful tokens.

Score Reporting

Errors specific to /reportScore (V3 quality feedback).
  • ERROR_TASK_NOT_FOUND#

    /reportScore: the taskId doesn't belong to your account or has been purged.

    Fix: Score reports must reference a task you owned and must be filed within 24h of solve completion.

  • ERROR_TASK_NOT_READY#

    /reportScore: the task is still processing or already failed.

    Fix: Only `ready` tasks can be scored. Wait for /getTaskResult to return ready before reporting.

  • ERROR_REPORT_TOO_LATE#

    /reportScore: more than 24h elapsed since solve completion.

    Fix: Report scores within minutes of your siteverify call — that's when the data is most useful for our V3 quality dashboard.

Code Examples

Complete working examples in every major language. Copy, paste your API key, run.

solve.py
import requests, time

API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"

# Create task
task = requests.post(f"{API}/createTask", json={
    "clientKey": KEY,
    "task": {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": "https://example.com",
        "websiteKey": "0x4AAA..."
    }
}).json()

task_id = task["taskId"]

# Poll for result
while True:
    result = requests.post(f"{API}/getTaskResult", json={
        "clientKey": KEY,
        "taskId": task_id
    }).json()

    if result["status"] == "ready":
        token = result["solution"]["token"]
        print(f"Solved: {token[:50]}...")
        break
    elif result["status"] == "failed":
        print(f"Failed: {result.get('errorDescription')}")
        break

    time.sleep(1)