Error Codes

All errors follow the same shape regardless of which provider handled the request. The error field is the string name; message is a human-readable description.

{
  "error": "AUTH_INVALID",
  "message": "API key not found or invalid",
  "retryable": false
}

Authentication

Error	HTTP	Description
AUTH_INVALID	401	API key not found or invalid
AUTH_FORBIDDEN	403	Access denied (IP restriction or account suspended)
BALANCE_EMPTY	402	Account balance is zero or negative

Input Validation

Error	HTTP	Description
INPUT_MISSING	400	Required input field is missing
INPUT_BAD_TYPE	400	Unsupported input type or format
INPUT_TOO_SMALL	400	Input payload is too small
INPUT_TOO_LARGE	413	Input payload exceeds maximum size
METHOD_INVALID	400	Unknown method or captcha type

Solve Errors

Error	HTTP	Retryable	Description
CAPACITY	429	Yes	No workers available; try again later
UNSOLVABLE	422	Yes	Could not solve after multiple attempts
NOT_FOUND	404	No	Task not found or expired
PROVIDER_TIMEOUT	504	Yes	Captcha provider timed out
PROVIDER_SITEKEY	400	No	Provider rejected sitekey as invalid
PROVIDER_DOMAIN	400	No	Provider rejected domain for this sitekey

Proxy Errors

Returned when you supply a proxy in your request and it fails. All proxy errors have an HTTP status of 502 or 504.

Error	HTTP	Description
PROXY_REFUSED	502	Proxy connection refused
PROXY_TIMEOUT	504	Proxy connection timed out
PROXY_BANNED	502	Proxy IP banned by target service
PROXY_AUTH	502	Proxy authentication failed

Handling Errors

Check the retryable field in the response. If true, wait for the retryAfter seconds and try again. The Retry-After HTTP header is also set on retryable errors.

{
  "error": "CAPACITY",
  "message": "No workers available; try again later",
  "retryable": true,
  "retryAfter": 5
}

All SDKs handle retryable errors automatically when using sync solve methods. See the API documentation for full endpoint reference, or explore the official SDKs for built-in error handling in your language.