Errors

Every response carries errorId: 0 on success or errorId: 1 on failure. When it is 1, errorCode names the problem and errorDescription explains it in plain text.

Error shape

Success responses use errorId: 0. Failures use errorId: 1 with a stable errorCode you can branch on and a human-readable errorDescription. Some codes add extra context, for example ERROR_WRONG_TASK_TYPE includes recommendedTaskType.

error.json

{
  "errorId": 1,
  "errorCode": "ERROR_WRONG_TASK_TYPE",
  "errorDescription": "This sitekey is reCAPTCHA v2, not Turnstile.",
  "recommendedTaskType": "RecaptchaV2TaskProxyLess"
}

Outcome errors are refunded

The four outcome errors, ERROR_TIMEOUT, ERROR_CAPTCHA_UNSOLVABLE, ERROR_NULL_RESULT, and ERROR_INTERNAL, are auto-refunded, as is a solve that could not start because capacity was unavailable. You are only billed for successful solves.

Authentication

Problems with the key or source IP. See Authentication.

Code	Description
`ERROR_KEY_DOES_NOT_EXIST`	The clientKey was not recognized. Check for typos and confirm the key is active in the dashboard.
`ERROR_IP_NOT_ALLOWED`	The calling IP is not on the key's IP allowlist. Add it, or remove the allowlist.
`ERROR_IP_BLOCKED`	Requests from your source IP are blocked. Contact support if this is unexpected.

Validation

The request reached the API but something in the task is wrong.

Code	Description
`ERROR_INVALID_PARAMS`	The request body is malformed or missing required fields. Check the JSON against the task type.
`ERROR_BAD_SITEKEY`	The websiteKey is invalid or does not match the site. Re-read the sitekey from the widget.
`ERROR_TASK_NOT_SUPPORTED`	The requested task type is not available on your account or is not offered.
`ERROR_WRONG_TASK_TYPE`	The challenge does not match the type you sent. The response includes recommendedTaskType; retry with it.
`ERROR_PROXY_REQUIRED`	This challenge is IP-bound and needs the proxy task variant. Supply proxy fields.
`ERROR_NO_PROXY`	Proxy fields are missing or incomplete on a task that requires them. Provide proxyType, proxyAddress, proxyPort.
`ERROR_PROXY_CONNECT_REFUSED`	Capzy could not connect to the proxy you supplied. Verify host, port, and credentials.
`ERROR_INVALID_TASK_DATA`	A task-specific field is present but invalid (bad URL, malformed value, etc.).
`ERROR_SITE_BLOCK`	The target site is blocking solves for this challenge. Retry later or adjust the approach.

Rate and capacity

You are sending faster than allowed, or the platform is momentarily saturated.

Code	Description
`ERROR_MAX_TASKS_REACHED`	You have too many tasks in flight. Wait for some to finish or raise concurrency with a plan.
`ERROR_RATE_LIMITED`	You exceeded the request rate. Back off and retry with a short delay.
`ERROR_NO_SLOT_AVAILABLE`	No solving capacity is free right now. Retry shortly; createTask is not charged when this happens.

Outcome

The task was accepted and billed at createTask, but the solve itself did not succeed. The refundable codes are auto-refunded.

Code	Description
`ERROR_TIMEOUT`	The solve did not finish in time. Auto-refunded. Retry, ideally with a cleaner proxy.
`ERROR_CAPTCHA_UNSOLVABLE`	The challenge could not be solved this attempt. Auto-refunded. Retry.
`ERROR_NULL_RESULT`	The solve produced no usable result. Auto-refunded. Retry.
`ERROR_INTERNAL`	An internal error occurred during solving. Auto-refunded. Retry.
`ERROR_ZERO_BALANCE`	Your account balance is zero. Top up before creating more tasks.

Reporting

Returned by the report endpoints. See Reporting outcomes.

Code	Description
`ERROR_TASK_NOT_FOUND`	The taskId in a report call does not exist for this key.
`ERROR_TASK_NOT_READY`	You reported a task that is not in ready status. Only ready tasks can be reported.
`ERROR_REPORT_TOO_LATE`	The report arrived after the 24-hour window, or the task was already reported once.

For the default limits (about 30 concurrent tasks and 30 requests per second), see Using proxies and Getting the result for how the poll loop interacts with them.

Reporting outcomes

Cloudflare