API referenceReferenceError codes

Error codes

Every failure is an HTTP 200 with errorId set to 1. Read the body, never the status line: a 4xx or 5xx from us means the request never reached the service.

The shape of an error

JSON

{
  "errorId": 1,
  "errorCode": "ERROR_KEY_DENIED_ACCESS",
  "errorDescription": "That client key is not on any account.",
  "taskId": ""
}

Field	Type	What it means
`errorId`	Integer	0 for fine, 1 for failed. Nothing else.
`errorCode`	String	A stable string. Branch on this.
`errorDescription`	String	One sentence for a human. Wording may change; do not match on it.

Account and key

Code	What happened	What to do
`ERROR_KEY_DENIED_ACCESS`	The key is not on any account.	Copy it again from the dashboard. Watch for trailing whitespace.
`ERROR_ZERO_BALANCE`	Not enough left to cover the task.	Add funds. Queued tasks still finish.
`ERROR_SETTLEMENT_FAILED`	The solve worked, the billing did not.	Retry. The task was not charged.
`ERROR_KEY_TEMP_BLOCKED`	Too many failed requests on this key.	It clears itself after 5 minutes. Fix the request first.
`ERROR_IP_BANNED`	Too many errors from one address.	It clears after 30 minutes. This is almost always a loop with no sleep.

The request itself

Code	What happened	What to do
`ERROR_INVALID_TASK_DATA`	A field is missing or malformed.	Read `errorDescription`. It names the field.
`ERROR_TASK_NOT_SUPPORTED`	No such task type.	Check spelling and case. Type strings are case sensitive.
`ERROR_BAD_REQUEST`	The body did not parse as JSON.	Check the content type header and the encoding.
`ERROR_TASKID_INVALID`	No such id, or it is older than 5 minutes, or you have polled 120 times.	Create the task again.
`ERROR_RATE_LIMIT`	Too many requests in too short a window.	Back off. Doubling the wait each time clears it fastest.

The solve

Code	What happened	What to do
`ERROR_CAPTCHA_UNSOLVABLE`	We could not answer it.	Not billed. Retry once; a second failure usually means the wrong type.
`ERROR_TASK_TIMEOUT`	Nothing after 120 seconds.	Not billed. Retry.
`ERROR_PROXY_BANNED`	The target site blocks your proxy address.	Rotate the address.
`ERROR_PROXY_CONNECT_REFUSED`	We could not reach your proxy at all.	Check the port and the firewall. Not billed.
`ERROR_PROXY_AUTH_FAILED`	The proxy rejected the username or password.	Check the credentials. Not billed.
`ERROR_SERVICE_UNAVAILABLE`	We are under load or down.	Retry after a few seconds. Status is on the dashboard.

What to retry, and what not to

Retry ERROR_SERVICE_UNAVAILABLE, ERROR_RATE_LIMIT, ERROR_SETTLEMENT_FAILED and ERROR_TASK_TIMEOUT, backing off each time.
Retry ERROR_CAPTCHA_UNSOLVABLE once, then stop and look at the task type.
Never retry ERROR_KEY_DENIED_ACCESS, ERROR_TASK_NOT_SUPPORTED or ERROR_INVALID_TASK_DATA. The same request will fail the same way and walk you into a block.

Last updated 21 September 2026