Errors

ZeroCaptcha reports an error in the shape of the dialect you called. Every code on this page has its own anchor, named after the code, such as #insufficient_funds or #ERROR_ZERO_BALANCE. A problem’s type links straight to its entry.

What errors cost

A refused request costs nothing, whatever the code.
A task that fails or expires costs nothing: the price held when it was created goes back to your balance in full.
A task that succeeded is charged, even if you read it after its token expired (ERROR_TOKEN_EXPIRED).

How an error looks

The REST API answers every failed call with RFC 9457 problem details, served as application/problem+json with a 4xx or 5xx status.

{
  "type": "https://zerocaptcha.io/docs/reference/errors/#insufficient_funds",
  "title": "Insufficient funds",
  "status": 402,
  "detail": "Your balance cannot cover this task. Add funds and try again.",
  "instance": "/v1/tasks",
  "code": "insufficient_funds",
  "request_id": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
}

Field	Meaning
`type`	A link to this page’s entry for the code
`title`	A short, fixed summary of the problem
`status`	The HTTP status, repeated for convenience
`detail`	What happened in this request; never sent with a 5xx
`instance`	The path that was called
`code`	A stable, machine-readable code; branch on this, not on the title
`request_id`	The ID to quote to support; also sent in the `x-request-id` header

The compatible endpoints, createTask, getTaskResult and getBalance, answer in their own shape instead: HTTP 200 with errorId 1.

{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "Your balance cannot cover this task. Add funds and try again."
}

A request can still fail before it reaches either shape, for example at a proxy, on a body that is too large or on a server timeout. Those failures come back as a 4xx or 5xx status, so check the HTTP status as well as errorId. The quickstart samples do both.

Retrying

Retry with backoff: internal_error, service_unavailable, request_timeout and ERROR_SERVICE_UNAVAILABLE.
Retry after a wait: queue_full and idempotency_key_in_use, after the time in their Retry-After header; ERROR_NO_SLOT_AVAILABLE and ERROR_IDEMPOTENCY_KEY_IN_USE, after a few seconds.
Fix the request first: every other code fails the same way until something changes, such as the key, the balance or the request itself.

When you retry a create, send the same Idempotency-Key header, on POST /v1/tasks or POST /createTask. For 24 hours the same key and request return the first reply instead of making a second task. A task that failed will not change either: create a new one.

Asking for help

Quote the request_id of a failed REST call, or the taskId of a task. Never send your API key: support never needs it, and anyone who has it can spend your balance.

Problem codes

The code of a REST problem.

`bad_request`

HTTP 400 · Bad request

Meaning: The request is malformed in a way no more specific code covers, such as a missing or unsupported Content-Type. Other 4xx statuses without a code of their own also use it.
Retry: No. The same request fails the same way.
What to do: Compare the method, headers and body with the API reference, and send JSON with Content-Type: application/json.
Cost: Nothing. A refused request is never charged.

`not_found`

HTTP 404 · Not found

Meaning: No route matches the path, or no task or key with this ID belongs to your account.
Retry: No.
What to do: Check the path and the ID. A task or a key is visible only to its own account.
Cost: Nothing. Reads are never charged.
Related: ERROR_NO_SUCH_CAPCHA_ID

`method_not_allowed`

HTTP 405 · Method not allowed

Meaning: The path exists, but not with this HTTP method.
Retry: No.
What to do: Use the method the reference gives for the path, such as POST /v1/tasks to create a task.
Cost: Nothing. A refused request is never charged.

`payload_too_large`

HTTP 413 · Request body too large

Meaning: The request body is larger than the API accepts.
Retry: No.
What to do: Send only the documented fields. A task needs the page URL, its site key and, when you use them, action, cdata and a proxy.
Cost: Nothing. A refused request is never charged.

`internal_error`

HTTP 500 · Internal server error

Meaning: Something failed on our side. The reply has no detail; the cause is logged under its request ID.
Retry: Yes, with backoff. Retry a create with the same Idempotency-Key, so one that went through is not made twice.
What to do: If it keeps happening, contact support and quote the request_id.
Cost: Nothing for this reply. If a create went through before it, that task is charged only if it succeeds.

`service_unavailable`

HTTP 503 · Service unavailable

Meaning: A service the API depends on is down or overloaded, so the request could not be served.
Retry: Yes, after a short wait, with backoff.
What to do: Retry. If it lasts, check the status page.
Cost: Nothing. A refused request is never charged.
Related: ERROR_SERVICE_UNAVAILABLE

`request_timeout`

HTTP 504 · Request timed out

Meaning: The API did not finish the request in time. The timeout is on our side, not a slow client.
Retry: Yes, with backoff. Retry a create with the same Idempotency-Key: the first attempt may have created the task.
What to do: Retry. To check whether a create went through, list tasks with the idempotencyKey filter.
Cost: Nothing for this reply. If a create went through before it, that task is charged only if it succeeds.

`unauthorized`

HTTP 401 · Authentication required

Meaning: No valid API key or session came with the request: the Authorization header is missing or malformed, or the key does not exist.
Retry: Not with the same key.
What to do: Send Authorization: Bearer followed by a key from the dashboard, and check that the whole key was copied.
Cost: Nothing. A refused request is never charged.
Related: ERROR_KEY_DOES_NOT_EXIST

`invalid_credentials`

HTTP 401 · Wrong email or password

Meaning: Dashboard log-in only: the email and password do not match an account.
Retry: Not with the same details.
What to do: Check the email address and the password, then log in again.
Cost: Nothing. A refused request is never charged.

`key_revoked`

HTTP 401 · API key revoked

Meaning: The key was revoked, or it was rotated and its overlap has ended, so it can no longer call the API. The detail says which.
Retry: No.
What to do: Use the key that replaced it, or create a new key in the dashboard, and replace the old one wherever it is used.
Cost: Nothing. A refused request is never charged.
Related: ERROR_KEY_REVOKED

`key_limit_reached`

HTTP 409 · Key limit reached

Meaning: Dashboard only: the account has as many active API keys as it may. A key being replaced by a rotation, and a revoked key, does not count.
Retry: Not until a key is revoked.
What to do: Revoke a key you no longer use, then create the new one. To replace a key, rotate it instead: a rotation never needs a free place.
Cost: Nothing. A refused request is never charged.

`key_state_conflict`

HTTP 409 · Key cannot change this way

Meaning: Dashboard only: the key cannot change this way. It no longer works, so it cannot be renamed, restricted or rotated; it was rotated already, so it cannot be rotated again; or it was never rotated, so it has no overlap to end.
Retry: No. The same change fails the same way.
What to do: Reload the key to see where it stands. Rotate the key that replaced it, revoke a key to stop it at once, or create a new key.
Cost: Nothing. A refused request is never charged.

`csrf_rejected`

HTTP 403 · Cross-site request refused

Meaning: Dashboard sessions only: a browser request came from another site, or without the session's CSRF token.
Retry: Not as it was sent.
What to do: In the dashboard, reload the page. From code, call the API with an API key instead.
Cost: Nothing. A refused request is never charged.

`insufficient_scope`

HTTP 403 · API key lacks the scope

Meaning: The key lacks the scope this call needs: tasks:write to create tasks, tasks:read to read them and balance:read for the balance. No API key may manage keys: that takes a dashboard session.
Retry: Not with this key.
What to do: Use a key with the scope the detail names, or create one that has it. Manage keys from the dashboard.
Cost: Nothing. A refused request is never charged.
Related: ERROR_ACCESS_DENIED

`ip_not_allowed`

HTTP 403 · Address not allowed for this key

Meaning: The key works only from the addresses on its allowlist, and this request came from another.
Retry: Not from this address.
What to do: Add the address to the key's allowlist in the dashboard, or call from an allowed address.
Cost: Nothing. A refused request is never charged.
Related: ERROR_IP_NOT_ALLOWED

`account_suspended`

HTTP 403 · Account suspended

Meaning: The account is suspended: its keys are refused, and it cannot create tasks, make keys or add funds.
Retry: No.
What to do: Contact support to appeal.
Cost: Nothing. A refused request is never charged.
Related: ERROR_ACCOUNT_SUSPENDED

`insufficient_funds`

HTTP 402 · Insufficient funds

Meaning: Your available balance cannot cover the task's price. Prices held for tasks still running count against it.
Retry: Yes, once the balance covers the price: after a top-up, or when running tasks finish and their holds are released or charged.
What to do: Add funds in the dashboard, then create the task again.
Cost: Nothing. A refused request is never charged.
Related: ERROR_ZERO_BALANCE

`domain_blocked`

HTTP 403 · Domain blocked

Meaning: Tasks for this site are not allowed: it is in a category the Acceptable Use Policy excludes, such as banking or government, or its owner opted out.
Retry: No. The same site is refused every time.
What to do: Do not send tasks for this site.
Cost: Nothing. A refused request is never charged.
Related: ERROR_DOMAIN_BLOCKED

`validation_failed`

HTTP 422 · Invalid request

Meaning: A field is missing or has an invalid value, such as an unsupported task type, a websiteURL that is not a URL, or a proxy on a proxyless task. The detail names the field.
Retry: Only after fixing the request.
What to do: Fix the field the detail names, then send the request again.
Cost: Nothing. A refused request is never charged.
Related: ERROR_TASK_ABSENT, ERROR_TASK_NOT_SUPPORTED, ERROR_INVALID_TASK_DATA

`idempotency_key_reused`

HTTP 422 · Idempotency key reused

Meaning: This Idempotency-Key was used within the last 24 hours for a different request.
Retry: Not with this key.
What to do: Use a new key for a new task. Reuse a key only to retry exactly the same request.
Cost: Nothing. A refused request is never charged.
Related: ERROR_IDEMPOTENCY_KEY_REUSED

`idempotency_key_in_use`

HTTP 409 · Idempotency key in use

Meaning: A request with this Idempotency-Key is still being processed.
Retry: Yes, after the wait in the Retry-After header. The retry gets the first request's reply.
What to do: Wait, then send the same request with the same key.
Cost: Nothing extra. The first request's task, if it made one, is charged only if it succeeds.
Related: ERROR_IDEMPOTENCY_KEY_IN_USE

`queue_full`

HTTP 429 · Queue full

Meaning: Your account's share of the queue, or the solver pool, is full.
Retry: Yes, after the wait in the Retry-After header.
What to do: Wait, then retry, and spread tasks out over time.
Cost: Nothing. A refused request is never charged.
Related: ERROR_NO_SLOT_AVAILABLE

`rate_limited`

HTTP 429 · Too many requests

Meaning: The request is over a budget: reads of tasks and the balance for your key or account, sign-in attempts from your address or failures for an email, sign-ups, password reset requests and uses of email links from your address or for an email, emails asked for by one person, or the live streams your account may hold open. Creating tasks has no budget: your balance and your share of the queue bound it instead. The RateLimit and RateLimit-Policy headers show where the key's and account's budgets stand.
Retry: Yes, after the wait in the Retry-After header.
What to do: Wait, then retry, and pace requests by the RateLimit header: poll results less often, or close a live stream you no longer need.
Cost: Nothing. A refused request is never charged.
Related: ERROR_RATE_LIMIT

`reauthentication_required`

HTTP 403 · Recent sign-in required

Meaning: The change needs a recent sign-in, such as changing the email address or the password, or turning two-factor or a passkey on or off, and the session last proved who it is longer ago than the account policy's reauthenticationWindow. Managing API keys never needs one.
Retry: Yes, after re-authenticating.
What to do: Confirm the password with POST /v1/session/reauthentication, then send the change again.
Cost: Nothing. A refused request is never charged.

`link_invalid`

HTTP 400 · Link not valid

Meaning: The email link is not one this service made, or not all of it arrived, as when a mail client cuts a long link short.
Retry: No. The same link fails the same way.
What to do: Open the link straight from the email, or copy all of it. If it still fails, ask for a new email.
Cost: Nothing. A refused request is never charged.

`link_expired`

HTTP 410 · Link expired

Meaning: The email link is past its lifetime, or was replaced: by a newer reset link, a change of address, or a password changed since it was sent.
Retry: No. Ask for a new link instead.
What to do: Ask for a new verification email or a new password reset email; the page that opened the link offers it.
Cost: Nothing. A refused request is never charged.

`link_used`

HTTP 409 · Link already used

Meaning: The email link was already used. Each link works once.
Retry: No.
What to do: Nothing, if the address is verified or the password was reset already: sign in. Otherwise ask for a new email.
Cost: Nothing. A refused request is never charged.

`weak_password`

HTTP 422 · Password not allowed

Meaning: The new password breaks a rule: it has fewer than 8 characters, is the account's email address, or is a common password. The problem's detail says which.
Retry: No. Choose another password.
What to do: Use at least 8 characters, not the email address and not a common password. A password manager's generated password passes.
Cost: Nothing. A refused request is never charged.

`state_conflict`

HTTP 409 · Not possible now

Meaning: What was asked conflicts with where the resource stands, such as asking for a verification email for an address that is verified already, or registering a passkey that is registered already.
Retry: No. The same request fails until the state changes.
What to do: Read the resource again, such as GET /v1/session, and act on what it shows.
Cost: Nothing. A refused request is never charged.

`role_required`

HTTP 403 · Role required

Meaning: The signed-in person's role does not allow the action: in the dashboard, a member doing what only an owner may, such as managing keys, billing or the team; in the staff console, a staff member without the role the action needs.
Retry: Not until an owner or admin gives the person a role that allows it.
What to do: Ask an owner of the account (or, for staff, an admin) for the role, or leave the action to someone who holds it.
Cost: Nothing. A refused request is never charged.

`spend_cap_reached`

HTTP 402 · Spend cap reached

Meaning: The API key has a daily spend cap, and this task would take what its tasks created today (UTC) hold or were charged past it. Tasks that failed or expired do not count.
Retry: Not before 00:00 UTC, when the day's count starts again, unless the cap is raised or removed.
What to do: Raise or remove the key's cap in the dashboard, use another key, or wait for the next UTC day.
Cost: Nothing. A refused request is never charged.
Related: ERROR_SPEND_CAP_REACHED

`payments_unavailable`

HTTP 503 · Payments unavailable

Meaning: A top-up cannot be started now: no payment processor is set up, or it did not answer. Balances, tasks and receipts are unaffected.
Retry: Yes, after a few minutes.
What to do: Try the top-up again later. If it lasts, contact support.
Cost: Nothing. No invoice was created and nothing was charged.

`email_taken`

HTTP 409 · Email already registered

Meaning: Sign-up only: this email address already has an account. The detail says: This email already has an account. Log in or reset your password.
Retry: No. The same address is refused every time.
What to do: Log in with the address, or reset its password if you have forgotten it. To open another account, use another address.
Cost: Nothing. A refused request is never charged.

`email_unverified`

HTTP 403 · Email not confirmed

Meaning: Dashboard only: creating an API key or starting a top-up needs the signed-in owner's email address confirmed, and it is not yet. Keys the account already has keep working, and everything else in the dashboard works as before.
Retry: Not until the address is confirmed. Then the same request succeeds at once.
What to do: Open the link in the email ZeroCaptcha sent when you signed up. If it is lost or expired, send a new one from the dashboard, or with POST /v1/email-verification/resend. Wrong address? Change it in Settings.
Cost: Nothing. A refused request is never charged.

Compatible codes

The errorCode of a compatible reply with errorId 1.

`ERROR_TASK_ABSENT`

Meaning: The body has no task object, or the task has no type.
Retry: Only after fixing the request.
What to do: Send a task with a type, such as TurnstileTaskProxyless.
Cost: Nothing. A refused request is never charged.
Related: validation_failed

`ERROR_TASK_NOT_SUPPORTED`

Meaning: The task type is not one ZeroCaptcha solves.
Retry: Only with a supported type.
What to do: Use TurnstileTaskProxyless, TurnstileTask with your proxy, or CloudflareChallengeTask with your proxy for a challenge page. AntiTurnstileTaskProxyLess, AntiTurnstileTask and AntiCloudflareTask work too, as the same tasks. A challenge page without a proxy is refused this way too: its clearance would not work from your address.
Cost: Nothing. A refused request is never charged.
Related: validation_failed

`ERROR_INVALID_TASK_DATA`

Meaning: A task field is missing or invalid: a websiteURL that is not a URL, no websiteKey on a Turnstile task, a proxy on a proxyless task or none on TurnstileTask or a challenge page. The errorDescription names the problem. As a task outcome, the solver refused the task's parameters after it was queued.
Retry: Only after fixing the task.
What to do: Fix the field the errorDescription names, then create the task again.
Cost: Nothing. A refused request is never charged, and a task that fails this way is released in full.
Related: validation_failed

`ERROR_KEY_DOES_NOT_EXIST`

Meaning: The clientKey is missing, or is not a valid key.
Retry: Not with the same key.
What to do: Send a key from the dashboard as clientKey, and check that the whole key was copied.
Cost: Nothing. A refused request is never charged.
Related: unauthorized

`ERROR_KEY_REVOKED`

Meaning: The key was revoked, or it was rotated and its overlap has ended, so it can no longer call the API. The errorDescription says which.
Retry: No.
What to do: Use the key that replaced it, or create a new key in the dashboard, and replace the old one wherever it is used.
Cost: Nothing. A refused request is never charged.
Related: key_revoked

`ERROR_ACCOUNT_SUSPENDED`

Meaning: The account is suspended. As a task outcome, it was suspended after the task was created and before it ran.
Retry: No.
What to do: Contact support to appeal.
Cost: Nothing. A refused request is never charged, and a task stopped this way is released in full.
Related: account_suspended

`ERROR_IP_NOT_ALLOWED`

Meaning: The key works only from the addresses on its allowlist, and this request came from another.
Retry: Not from this address.
What to do: Add the address to the key's allowlist in the dashboard, or call from an allowed address.
Cost: Nothing. A refused request is never charged.
Related: ip_not_allowed

`ERROR_ACCESS_DENIED`

Meaning: The key lacks the scope this call needs: tasks:write for createTask, tasks:read for getTaskResult and balance:read for getBalance.
Retry: Not with this key.
What to do: Use a key with the scope the errorDescription names, or create one that has it.
Cost: Nothing. A refused request is never charged.
Related: insufficient_scope

`ERROR_DOMAIN_BLOCKED`

Meaning: Tasks for this site are not allowed: it is in a category the Acceptable Use Policy excludes, or its owner opted out. As a task outcome, the site was blocked after the task was created.
Retry: No. The same site is refused every time.
What to do: Do not send tasks for this site.
Cost: Nothing. A refused request is never charged, and a task stopped this way is released in full.
Related: domain_blocked

`ERROR_ZERO_BALANCE`

Meaning: Your available balance cannot cover the task's price. Prices held for tasks still running count against it.
Retry: Yes, once the balance covers the price.
What to do: Add funds in the dashboard, then create the task again.
Cost: Nothing. A refused request is never charged.
Related: insufficient_funds

`ERROR_NO_SLOT_AVAILABLE`

Meaning: Your account's share of the queue, or the solver pool, is full.
Retry: Yes, after a few seconds, with backoff.
What to do: Wait, then retry, and spread tasks out over time.
Cost: Nothing. A refused request is never charged.
Related: queue_full

`ERROR_RATE_LIMIT`

Meaning: The call is over a budget of your key or account: getTaskResult and getBalance share one. createTask has none: your balance and your share of the queue bound it instead. The same condition as rate_limited, under the name clients of this format already handle.
Retry: Yes, after the wait in the Retry-After header.
What to do: Wait, then retry, and poll getTaskResult less often.
Cost: Nothing. A refused request is never charged.
Related: rate_limited

`ERROR_IDEMPOTENCY_KEY_REUSED`

Meaning: The Idempotency-Key header was used within the last 24 hours for a different createTask request.
Retry: Not with this key.
What to do: Use a new key for a new task. Reuse a key only to retry exactly the same request.
Cost: Nothing. A refused request is never charged.
Related: idempotency_key_reused

`ERROR_IDEMPOTENCY_KEY_IN_USE`

Meaning: A createTask request with this Idempotency-Key is still being processed.
Retry: Yes, shortly. The retry gets the first request's reply.
What to do: Wait a moment, then send the same request with the same key.
Cost: Nothing extra. The first request's task, if it made one, is charged only if it succeeds.
Related: idempotency_key_in_use

`ERROR_NO_SUCH_CAPCHA_ID`

Meaning: The taskId is missing, is not a task ID, or names no task of this key's account. CAPCHA is the dialect's own spelling.
Retry: No.
What to do: Poll with the taskId that createTask returned, using a key of the same account.
Cost: Nothing. Reads are never charged.
Related: not_found

`ERROR_SERVICE_UNAVAILABLE`

Meaning: The API could not serve the request right now.
Retry: Yes, with backoff. Retry createTask with the same Idempotency-Key header, so one that went through is not made twice.
What to do: Retry. If it lasts, check the status page.
Cost: Nothing for this reply. If a create went through before it, that task is charged only if it succeeds.
Related: service_unavailable

`ERROR_REPORT_NOT_RECORDED`

Meaning: A report (reportIncorrect, reportCorrect, their Recaptcha forms, or feedbackTask) named a task that did not succeed, so it has no token to report on.
Retry: No.
What to do: Report only tasks that succeeded. Reports are recorded for our staff and never refund a task.
Cost: Nothing. Reads are never charged.

`ERROR_DUPLICATE_REPORT`

Meaning: The task has a report already: one per task.
Retry: No.
What to do: Send one report per task.
Cost: Nothing. Reads are never charged.

`ERROR_INVALID_REQUEST`

Meaning: The body is not valid JSON, or is not a JSON object; or feedbackTask came without result.invalid.
Retry: Only after fixing the body.
What to do: Send a JSON object. The Content-Type does not matter here, so clients that send JSON as text/plain work.
Cost: Nothing. A refused request is never charged.

`ERROR_TOKEN_EXPIRED`

Meaning: getTaskResult only: the task succeeded, but its token has expired. Turnstile tokens work once, for 300 seconds. The reply keeps status ready and includes the cost.
Retry: No. A token cannot be renewed.
What to do: Create a new task, and use each token as soon as it is ready.
Cost: The task's price. It succeeded, so it was charged, even though its token expired before it was used.

`ERROR_SPEND_CAP_REACHED`

Meaning: createTask only: the API key's daily spend cap would be passed by this task. The same condition as spend_cap_reached.
Retry: Not before 00:00 UTC, unless the cap is raised or removed.
What to do: Raise or remove the key's cap in the dashboard, or wait for the next UTC day.
Cost: Nothing. A refused request is never charged.
Related: spend_cap_reached

Task outcomes

A task that was created can still fail. getTaskResult then answers errorId 1 with status failed and one of these codes; on REST, the task has status failed or expired, with the code in its errorCode. A task can also end with ERROR_DOMAIN_BLOCKED, ERROR_ACCOUNT_SUSPENDED or ERROR_INVALID_TASK_DATA when that check fails after the task was created. None of them is charged.

`ERROR_CAPTCHA_UNSOLVABLE`

Meaning: Every attempt to solve the challenge failed.
Retry: A new task may succeed.
What to do: If it keeps happening, check the websiteURL and websiteKey and, with TurnstileTask or a challenge page, that your proxy works.
Cost: Nothing. The price held when the task was created goes back to your balance in full.

`ERROR_TASK_TIMEOUT`

Meaning: The task was not solved before its deadline.
Retry: Yes, with a new task.
What to do: Create a new task. If timeouts keep happening, check the status page.
Cost: Nothing. The price held when the task was created goes back to your balance in full.

`ERROR_PROXY_NOT_ALLOWED`

Meaning: The proxy points at a private or reserved address, such as 127.0.0.1 or 10.0.0.0/8, which tasks cannot use.
Retry: Not with this proxy.
What to do: Use a proxy with a public address.
Cost: Nothing. The price held when the task was created goes back to your balance in full.

`ERROR_ACCOUNT_DELETED`

Meaning: An owner deleted the account while the task was queued, which cancels every task it had queued.
Retry: No. The account and its keys are gone.
What to do: Nothing to do. To start again, sign up for a new account.
Cost: Nothing. The price held when the task was created goes back to your balance in full.