Skip to content
documentation / api reference

api documentation

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

Quick Start

step 1
POST /createTask

Submit the captcha type + site params. Get a taskId back instantly.

step 2
POST /getTaskResult

Poll ~1s until status is ready. The token arrives in the solution object.

step 3
POST /getBalance

Check remaining credits. Failed solves refund here automatically.

base urlhttps://api.capzy.aiauth via clientKey in the request body

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.

Default
30 concurrent · 30 req/sec

Every new account starts here

Higher concurrent
300+ concurrent · 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.

    fixDouble-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.

    fixAdd 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.

    fixWe 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.

    fixCheck 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.

    fixMake 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.

    fixSee 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.

    fixWe 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.

    fixSwitch 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.

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

    #
  • ERROR_PROXY_CONNECT_REFUSED

    Your supplied proxy refused the connection.

    fixCheck 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.

    fixWait 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.

    fixSlow 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.

    fixRetry 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.

    fixStop 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.

    fixRetry 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.

    fixAuto-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.

    fixAuto-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.

    fixAuto-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.

    fixAuto-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.

    fixAdd 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.

    fixScore 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.

    fixOnly `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.

    fixReport 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)

Integrate in under 60 seconds.

$0.10 free credits on signup. No credit card required.

Get your free API key →