Errors

There are two kinds of errors. A request error means the request was rejected: no task was created and nothing was charged. A task failure means the task was created but could not be solved: it ends with status: "failed" and is not charged. Use the codes in programs; messages may change. New codes can be added at any time (Versioning).

Request errors (v1)

The native API returns errors as RFC 9457 problem details (application/problem+json). type ishttps://noptcha.com/docs/errors/<code>; every response carries request_id (also in theNoptcha-Request-Id header).

{
  "type": "https://noptcha.com/docs/errors/insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "code": "insufficient_balance",
  "detail": "Available $0.000300, task price $0.000900.",
  "request_id": "req_…"
}

code	HTTP	When
`invalid_request`	400	malformed body, missing field, bad parameter, `callback_url` not a string
`unsupported_type`	400	unknown or unavailable task type
`unauthorized`	401	invalid, revoked or expired key
`insufficient_balance`	402	balance too low for the task's price
`budget_exceeded`	402	the key's budget for the period is used up
`forbidden`	403	missing scope, IP not allowed, type not allowed, organization suspended
`not_found`	404	unknown endpoint or method; unknown, expired or foreign task; expired idempotent task
`idempotency_conflict`	409	same `Idempotency-Key` with another body, or still in progress
`task_not_solved`	409	feedback for a task that is still processing or failed
`request_too_large`	413	body over the limit
`invalid_params`	422	`params` or `metadata` do not match the schema, or `callback_url` is not allowed
`rate_limited`	429	over a rate limit, or IP blocked after invalid keys
`concurrency_limited`	429	too many tasks in flight
`internal`	500	our error
`service_unavailable`	503	no capacity or a dependency is down

422 invalid_params adds errors[] with one {pointer, message} per problem (at most 50, sorted by pointer; detail then ends with “and N more errors”); problems with an image also carry a reason (image_too_large, image_format, image_base64, image_empty; see Images).

Task failures

In the native API a failed task has status: "failed" and error: {code, message}, with a cost of zero:

error.code	Meaning
`unsolvable`	the captcha could not be solved (also when no solver accepts these parameters)
`timeout`	not solved before the type's deadline
`proxy_error`	the proxy could not be used
`invalid_site`	the site key or domain is invalid
`invalid_image`	the image is empty, too big or unreadable
`cancelled`	the task was cancelled

In the compatibility API a failed task is reported by getTaskResult with errorId: 1 and an error code such asERROR_CAPTCHA_UNSOLVABLE or one of the proxy codes below.

Compatibility API

Every response is HTTP 200; errorId is 0 on success and 1 on error, with errorCode anderrorDescription. The codes are the anti-captcha compatible ones:

errorCode	When
`ERROR_KEY_DOES_NOT_EXIST`	key malformed, unknown, revoked or expired; or the key lacks the scope this endpoint needs
`ERROR_ZERO_BALANCE`	balance too low, or the key's budget is used up
`ERROR_IP_NOT_ALLOWED`	client IP not in the key's allowlist
`ERROR_IP_BLOCKED`	too many invalid keys from this IP
`ERROR_ACCOUNT_SUSPENDED`	the organization is suspended
`ERROR_NO_SLOT_AVAILABLE`	no capacity, concurrency limit, create rate limit (also sandbox limits), temporary or internal error; retry later
`ERROR_TASK_NOT_SUPPORTED`	unknown task type name, or type not allowed for the key
`ERROR_TASK_ABSENT`	`task` missing or not an object (or the body could not be read)
`ERROR_NO_SUCH_CAPCHA_ID`	`taskId` missing, unknown, expired or of another organization; report for an unsolved task
`ERROR_INCORRECT_SESSION_DATA`	a parameter does not match the schema (`errorDescription` names it), or `callbackUrl` is not allowed
`ERROR_RECAPTCHA_INVALID_SITEKEY`	the site key is invalid (parameter check or solver)
`ERROR_RECAPTCHA_INVALID_DOMAIN`	the website URL, API domain or subdomain is invalid or not allowed
`ERROR_ZERO_CAPTCHA_FILESIZE`	the image is missing or empty
`ERROR_TOO_BIG_CAPTCHA_FILESIZE`	the image (characters or pixels) or the request body is too large
`ERROR_IMAGE_TYPE_NOT_SUPPORTED`	the image is not valid base64, not a PNG, JPEG, GIF, WebP or BMP image, or malformed or truncated (checked when the task is created); or the solver could not read it (task failed)
`ERROR_CAPTCHA_UNSOLVABLE`	the task failed: unsolvable, timed out, or no solver accepts these parameters
`ERROR_PROXY_CONNECT_REFUSED` `ERROR_PROXY_CONNECT_TIMEOUT` `ERROR_PROXY_READ_TIMEOUT` `ERROR_PROXY_BANNED` `ERROR_PROXY_TRANSPARENT` `ERROR_PROXY_HAS_NO_IMAGE_SUPPORT` `ERROR_PROXY_INCOMPATIBLE_HTTP_VERSION`	the proxy could not be used (task failed)
`ERROR_TOKEN_EXPIRED`	the solver reported the token expired (task failed)

Two responses come from the infrastructure rather than the protocol: HTTP 403 (problem details, forbidden) when a request does not pass through our edge network and HTTP 500 (internal). Treat both as transient. The 2captcha legacy API has its own codes, see 2captcha legacy API.

What to retry

Retry after a wait: rate_limited, concurrency_limited, service_unavailable, internal; ERROR_NO_SLOT_AVAILABLE. Honour Retry-After when present.
Fix first: everything else. Retrying an invalid request unchanged gives the same error.
Failed tasks are not charged; you may create a new task for the same captcha.
For POST /v1/tasks, send an Idempotency-Key so that a retry after a network error cannot create a second task (Idempotency).