Error Handling

Error Response Format

All API endpoints return errors in a consistent JSON format:

{
    "errorId": 1,
    "errorCode": "CAPTCHA_UNSOLVABLE",
    "errorDescription": "The captcha could not be solved. Check your parameters or try again."
}

Field	Type	Description
`errorId`	number	Error category (see below)
`errorCode`	string	Machine-readable error code
`errorDescription`	string	Human-readable error message

Error IDs

errorId	Category	Description
`0`	No Error	Task has no error
`1`	External Error	External provider error
`2`	Internal Error	Server-side error caused by AnySolver

When to Retry

errorId 1: Check your request parameters before retrying - errorId 2: Safe to retry after a short delay (1-5 seconds)

About error descriptions

Use errorCode for program logic. The examples on this page show the usual unified descriptions, but not every errorDescription is guaranteed to match these examples exactly. In some cases, AnySolver forwards a provider's original message to preserve better debugging context.

Error Codes Reference

All error codes returned by the API:

errorId	errorCode	errorDescription
1	CAPTCHA_UNSOLVABLE	The captcha could not be solved. Check your parameters or try again.
1	DOMAIN_BANNED	This domain is not allowed. Captchas from certain domains are forbidden.
1	ERROR_KEY_DOES_NOT_EXIST	Invalid or missing API key. Check your dashboard for the correct key.
1	ERROR_USER_BANNED	Account suspended due to improper API use. Contact support.
1	ERROR_ZERO_BALANCE	Insufficient account balance. Top up and retry.
1	IMAGE_CORRUPTED	Image is corrupted or unsupported format. Use JPG, PNG, or GIF.
1	IMAGE_TOO_LARGE	Image exceeds size limit. Reduce resolution or compress the file.
1	IMAGE_TOO_SMALL	Image is too small (< 100 bytes). Check that the file is valid.
2	INTERNAL_ERROR	An internal error occurred. Please try again later.
1	INVALID_DOMAIN	Domain mismatch or not allowed. Ensure domain matches sitekey.
1	INVALID_SITEKEY	Invalid websiteKey. Check the sitekey in the page source.
1	INVALID_TASK_DATA	Invalid or missing task parameters. Check request structure.
1	INVALID_USERAGENT	Invalid or expired User-Agent. Update to a current browser UA.
1	INVALID_WEBSITEURL	Invalid websiteURL format. Use full URL with http:// or https://.
1	NO_PROVIDERS_AVAILABLE	No providers available for this task type. Check task type or provider configuration.
2	PROVIDER_BALANCE_ERROR	Provider returned error when fetching balance: {errorDescription}
1	PROVIDER_BALANCE_NOT_SUPPORTED	Provider {provider} does not support balance checking.
2	PROVIDER_GLOBAL_LIMIT_REACHED	Provider usage limit reached. See https://docs.anysolver.com/errors/provider-limits for details.
2	PROVIDER_RATE_LIMITED	Provider rate limit reached. See https://docs.anysolver.com/errors/provider-limits for details.
2	PROVIDER_RESPONSE_MALFORMED	Provider response is malformed or missing required fields. Description varies on the cause of the error.
1	PROVIDER_TASK_NOT_SUPPORTED	Provider {provider} does not support task type {taskType}.
2	PROVIDER_UNREACHABLE	Could not connect to the solving provider. Try again later.
1	PROXY_AUTH_FAILED	Proxy authentication failed. Check proxyLogin and proxyPassword.
1	PROXY_BANNED	Proxy IP is banned by the target service. Use a different proxy.
1	PROXY_CONNECTION_FAILED	Failed to connect to proxy. Check IP, port, and availability.
1	PROXY_INCOMPATIBLE	Proxy is incompatible (transparent, no SSL, or wrong protocol version). Try HTTP instead of SOCKS.
1	PROXY_MISSING	Proxy required but not provided. Add proxyType, proxyAddress, proxyPort.
1	RATE_LIMITED	Request rate limit exceeded.
1	SERVICE_UNAVAILABLE	The provider is temporarily unavailable or out of capacity. Try again later.
1	TASK_NOT_FOUND	Task ID not found or expired. Request the result within 5 minutes.
1	TASK_NOT_SUPPORTED	The task type is not supported. Check the type parameter.
1	TASK_TIMEOUT	The task timed out. Try with a different proxy or retry later.
1	TOKEN_EXPIRED	The token or session has expired. Obtain a new token and retry.
2	TRANSFORMATION_ERROR	Failed to transform request.
1	UNKNOWN_PROVIDER_ERROR	Unknown provider error. This description is not static and varies on the cause of the error.
2	VALIDATION_ERROR	The validation of the request failed. Check if the task schema matches the documentation.

Common Error Scenarios

Authentication Errors

Invalid or missing API key issues.

Balance Errors

Insufficient funds or billing issues.

Task Errors

CAPTCHA solving failures.

Proxy Errors

Proxy connection or authentication failures.

Service Errors

Temporary provider capacity or availability issues.

Authentication Errors

{
    "errorId": 1,
    "errorCode": "ERROR_KEY_DOES_NOT_EXIST",
    "errorDescription": "Invalid or missing API key. Check your dashboard for the correct key."
}

Solution: Verify your clientKey is correct and active in the Dashboard → API Keys.

Balance Errors

{
    "errorId": 1,
    "errorCode": "ERROR_ZERO_BALANCE",
    "errorDescription": "Insufficient account balance. Top up and retry."
}

Solution: Add funds via the Billing page.

Task Errors

{
    "errorId": 1,
    "errorCode": "CAPTCHA_UNSOLVABLE",
    "errorDescription": "The captcha could not be solved. Check your parameters or try again."
}

Solution: Verify your task parameters (websiteURL, websiteKey) are correct. Some CAPTCHAs may require a proxy.

Proxy Errors

{
    "errorId": 1,
    "errorCode": "PROXY_CONNECTION_FAILED",
    "errorDescription": "Failed to connect to proxy. Check IP, port, and availability."
}

Solution: Verify your proxy is online and accessible. Check IP, port, username, and password.

Service Errors

{
    "errorId": 1,
    "errorCode": "SERVICE_UNAVAILABLE",
    "errorDescription": "The provider is temporarily unavailable or out of capacity. Try again later."
}

Solution: Retry after a short delay. If the issue continues, switch provider or try again later when capacity is available.

Best Practices

Always check errorId first A value of 0 means no error, anything else is an error.

Use errorCode for logic Use the machine-readable errorCode for error handling logic, not errorDescription.

Implement retry logic For internal errors (errorId 2), implement exponential backoff retry.

Log error details Store the full error response for debugging, especially when a provider-specific description is forwarded.

Example Error Handling

async function handleApiResponse(response) {
    const data = await response.json();

    if (data.errorId === 0) {
        return data; // No error
    }

    // Handle specific errors
    switch (data.errorCode) {
        case 'ERROR_ZERO_BALANCE':
            throw new Error('Insufficient balance. Please top up.');
        case 'CAPTCHA_UNSOLVABLE':
            throw new Error('CAPTCHA could not be solved. Retrying...');
        case 'RATE_LIMITED':
            await sleep(5000);
            return retry();
        default:
            throw new Error(data.errorDescription);
    }
}

Provider Usage Limits

Learn about provider-specific limits and how to handle them.

API Reference

Complete documentation for all endpoints and request formats.

Error Response Format

All API endpoints return errors in a consistent JSON format:

{
    "errorId": 1,
    "errorCode": "CAPTCHA_UNSOLVABLE",
    "errorDescription": "The captcha could not be solved. Check your parameters or try again."
}

Field	Type	Description
`errorId`	number	Error category (see below)
`errorCode`	string	Machine-readable error code
`errorDescription`	string	Human-readable error message

Error IDs

errorId	Category	Description
`0`	No Error	Task has no error
`1`	External Error	External provider error
`2`	Internal Error	Server-side error caused by AnySolver

When to Retry

errorId 1: Check your request parameters before retrying - errorId 2: Safe to retry after a short delay (1-5 seconds)

About error descriptions

Error Codes Reference

All error codes returned by the API:

errorId	errorCode	errorDescription
1	CAPTCHA_UNSOLVABLE	The captcha could not be solved. Check your parameters or try again.
1	DOMAIN_BANNED	This domain is not allowed. Captchas from certain domains are forbidden.
1	ERROR_KEY_DOES_NOT_EXIST	Invalid or missing API key. Check your dashboard for the correct key.
1	ERROR_USER_BANNED	Account suspended due to improper API use. Contact support.
1	ERROR_ZERO_BALANCE	Insufficient account balance. Top up and retry.
1	IMAGE_CORRUPTED	Image is corrupted or unsupported format. Use JPG, PNG, or GIF.
1	IMAGE_TOO_LARGE	Image exceeds size limit. Reduce resolution or compress the file.
1	IMAGE_TOO_SMALL	Image is too small (< 100 bytes). Check that the file is valid.
2	INTERNAL_ERROR	An internal error occurred. Please try again later.
1	INVALID_DOMAIN	Domain mismatch or not allowed. Ensure domain matches sitekey.
1	INVALID_SITEKEY	Invalid websiteKey. Check the sitekey in the page source.
1	INVALID_TASK_DATA	Invalid or missing task parameters. Check request structure.
1	INVALID_USERAGENT	Invalid or expired User-Agent. Update to a current browser UA.
1	INVALID_WEBSITEURL	Invalid websiteURL format. Use full URL with http:// or https://.
1	NO_PROVIDERS_AVAILABLE	No providers available for this task type. Check task type or provider configuration.
2	PROVIDER_BALANCE_ERROR	Provider returned error when fetching balance: {errorDescription}
1	PROVIDER_BALANCE_NOT_SUPPORTED	Provider {provider} does not support balance checking.
2	PROVIDER_GLOBAL_LIMIT_REACHED	Provider usage limit reached. See https://docs.anysolver.com/errors/provider-limits for details.
2	PROVIDER_RATE_LIMITED	Provider rate limit reached. See https://docs.anysolver.com/errors/provider-limits for details.
2	PROVIDER_RESPONSE_MALFORMED	Provider response is malformed or missing required fields. Description varies on the cause of the error.
1	PROVIDER_TASK_NOT_SUPPORTED	Provider {provider} does not support task type {taskType}.
2	PROVIDER_UNREACHABLE	Could not connect to the solving provider. Try again later.
1	PROXY_AUTH_FAILED	Proxy authentication failed. Check proxyLogin and proxyPassword.
1	PROXY_BANNED	Proxy IP is banned by the target service. Use a different proxy.
1	PROXY_CONNECTION_FAILED	Failed to connect to proxy. Check IP, port, and availability.
1	PROXY_INCOMPATIBLE	Proxy is incompatible (transparent, no SSL, or wrong protocol version). Try HTTP instead of SOCKS.
1	PROXY_MISSING	Proxy required but not provided. Add proxyType, proxyAddress, proxyPort.
1	RATE_LIMITED	Request rate limit exceeded.
1	SERVICE_UNAVAILABLE	The provider is temporarily unavailable or out of capacity. Try again later.
1	TASK_NOT_FOUND	Task ID not found or expired. Request the result within 5 minutes.
1	TASK_NOT_SUPPORTED	The task type is not supported. Check the type parameter.
1	TASK_TIMEOUT	The task timed out. Try with a different proxy or retry later.
1	TOKEN_EXPIRED	The token or session has expired. Obtain a new token and retry.
2	TRANSFORMATION_ERROR	Failed to transform request.
1	UNKNOWN_PROVIDER_ERROR	Unknown provider error. This description is not static and varies on the cause of the error.
2	VALIDATION_ERROR	The validation of the request failed. Check if the task schema matches the documentation.

Common Error Scenarios

Authentication Errors

Invalid or missing API key issues.

Balance Errors

Insufficient funds or billing issues.

Task Errors

CAPTCHA solving failures.

Proxy Errors

Proxy connection or authentication failures.

Service Errors

Temporary provider capacity or availability issues.

Authentication Errors

{
    "errorId": 1,
    "errorCode": "ERROR_KEY_DOES_NOT_EXIST",
    "errorDescription": "Invalid or missing API key. Check your dashboard for the correct key."
}

Solution: Verify your clientKey is correct and active in the Dashboard → API Keys.

Balance Errors

{
    "errorId": 1,
    "errorCode": "ERROR_ZERO_BALANCE",
    "errorDescription": "Insufficient account balance. Top up and retry."
}

Solution: Add funds via the Billing page.

Task Errors

{
    "errorId": 1,
    "errorCode": "CAPTCHA_UNSOLVABLE",
    "errorDescription": "The captcha could not be solved. Check your parameters or try again."
}

Solution: Verify your task parameters (websiteURL, websiteKey) are correct. Some CAPTCHAs may require a proxy.

Proxy Errors

{
    "errorId": 1,
    "errorCode": "PROXY_CONNECTION_FAILED",
    "errorDescription": "Failed to connect to proxy. Check IP, port, and availability."
}

Solution: Verify your proxy is online and accessible. Check IP, port, username, and password.

Service Errors

{
    "errorId": 1,
    "errorCode": "SERVICE_UNAVAILABLE",
    "errorDescription": "The provider is temporarily unavailable or out of capacity. Try again later."
}

Solution: Retry after a short delay. If the issue continues, switch provider or try again later when capacity is available.

Best Practices

Always check errorId first A value of 0 means no error, anything else is an error.

Use errorCode for logic Use the machine-readable errorCode for error handling logic, not errorDescription.

Implement retry logic For internal errors (errorId 2), implement exponential backoff retry.

Log error details Store the full error response for debugging, especially when a provider-specific description is forwarded.

Example Error Handling

async function handleApiResponse(response) {
    const data = await response.json();

    if (data.errorId === 0) {
        return data; // No error
    }

    // Handle specific errors
    switch (data.errorCode) {
        case 'ERROR_ZERO_BALANCE':
            throw new Error('Insufficient balance. Please top up.');
        case 'CAPTCHA_UNSOLVABLE':
            throw new Error('CAPTCHA could not be solved. Retrying...');
        case 'RATE_LIMITED':
            await sleep(5000);
            return retry();
        default:
            throw new Error(data.errorDescription);
    }
}

Provider Usage Limits

Learn about provider-specific limits and how to handle them.

API Reference

Complete documentation for all endpoints and request formats.

Error Handling

Error Response Format

Error IDs

Error Codes Reference

Common Error Scenarios

Authentication Errors

Balance Errors

Task Errors

Proxy Errors

Service Errors

Best Practices

Example Error Handling

On this page

Error Handling

Error Response Format

Error IDs

Error Codes Reference

Common Error Scenarios

Authentication Errors

Balance Errors

Task Errors

Proxy Errors

Service Errors

Best Practices

Example Error Handling

On this page