Errors

Scrapely uses standard HTTP status codes to indicate the success or failure of an API request. The exact error.id returned in the JSON payload will tell you exactly what went wrong. If you are using the Python SDK, these error IDs are automatically converted into native Python exceptions inheriting from the ScrapelyException base class.

REST API
Python SDK

When using the REST API directly, errors are returned as a JSON object with an appropriate HTTP status code.

{
  "success": false,
  "error": {
    "id": "API_KEY_INVALID",
    "message": "Invalid API key"
  }
}

The Python SDK raises specific exceptions. You can catch the specific error or catch the base ScrapelyException.

from scrapely import Scrapely
from scrapely.models.exceptions import ScrapelyException, APIKeyInvalid

client = Scrapely(api_key="INVALID_KEY")

try:
    task = client.crawler.crawl(website_url="https://example.com")
except APIKeyInvalid as e:
    print(f"Auth error: {e.message} (Status: {e.status_code})")
except ScrapelyException as e:
    print(f"API error: {e.message}")

Detailed Error Codes

Below is a comprehensive list of every error ID returned by the Scrapely API, its corresponding HTTP status code, and its meaning. In the Python SDK, these translate directly to PascalCase exception classes (e.g. API_KEY_INVALID becomes APIKeyInvalid).

Authentication & Account Errors

Error ID	HTTP Code	Description
`API_KEY_REQUIRED`	400	API key is required (via ‘api_key’ field or ‘X-API-Key’ header).
`API_KEY_INVALID`	403	Invalid API key provided.
`USER_NOT_FOUND`	403	No user found associated with the API key.
`SUBSCRIPTION_INACTIVE`	403	Your subscription is not active.
`CONCURRENCY_LIMIT_REACHED`	429	You have exceeded your active concurrency limit.
`TASK_ACCESS_DENIED`	403	You don’t have permission to access this task.

General Request Errors

Error ID	HTTP Code	Description
`INVALID_FIELDS`	400	Unrecognized fields were provided in the root of the JSON body.
`AMBIGUOUS_TASK_TYPE`	400	Cannot provide both ‘captcha’ and ‘crawler’ objects in one request.
`TASK_TYPE_REQUIRED`	400	Either a ‘captcha’ or ‘crawler’ object is required.
`TASK_ID_REQUIRED`	400	Task ID is required to fetch a result.
`INVALID_ENDPOINT`	400	Hit the wrong endpoint (e.g. fetching result from `/create`).
`TASK_NOT_FOUND`	404	The requested task ID does not exist.
`TASK_CREATION_FAILED`	500	Failed to create the task in the database.
`INTERNAL_SERVER_ERROR`	500	An unexpected internal error occurred.

Crawler Errors

Error ID	HTTP Code	Description
`INVALID_CRAWLER_FIELDS`	400	Unrecognized fields provided in the crawler object.
`CRAWLER_WEBSITE_URL_REQUIRED`	400	Crawler websiteURL is required.
`CRAWLER_WEBSITE_URL_INVALID_TYPE`	400	Crawler websiteURL must be a string.
`CRAWLER_WEBSITE_URL_INVALID_SCHEME`	400	Crawler websiteURL must start with http:// or https://.
`CRAWLER_WEBSITE_URL_TOO_LONG`	400	Crawler websiteURL must not exceed 254 characters.
`CRAWLER_BLOCK_RESOURCES_INVALID_TYPE`	400	Crawler block_resources must be a boolean.
`CRAWLER_DEVICE_INVALID_TYPE`	400	Crawler device must be a string.
`CRAWLER_DEVICE_INVALID_VALUE`	400	Crawler device must be either ‘desktop’ or ‘mobile’.
`CRAWLER_SCREENSHOT_INVALID_TYPE`	400	Crawler screenshot must be a boolean.
`CRAWLER_SCREENSHOT_FULL_PAGE_INVALID_TYPE`	400	Crawler screenshot_full_page must be a boolean.
`CRAWLER_SCREENSHOT_CONFLICT`	400	Cannot use both screenshot and screenshot_full_page at the same time.
`CRAWLER_RETURN_PAGE_SOURCE_INVALID_TYPE`	400	Crawler return_page_source must be a boolean.
`CRAWLER_RETURN_PAGE_TEXT_INVALID_TYPE`	400	Crawler return_page_text must be a boolean.
`CRAWLER_RETURN_PAGE_CONFLICT`	400	Cannot request both return_page_source and return_page_text at the same time.
`CRAWLER_RETURN_PAGE_COOKIES_INVALID_TYPE`	400	Crawler return_page_cookies must be a boolean.
`CRAWLER_RETURN_PAGE_META_INVALID_TYPE`	400	Crawler return_page_meta must be a boolean.
`CRAWLER_RETURN_USER_AGENT_INVALID_TYPE`	400	Crawler return_user_agent must be a boolean.
`CRAWLER_INSTRUCTIONS_INVALID_TYPE`	400	Crawler instructions must be a list.
`CRAWLER_INSTRUCTIONS_EMPTY`	400	Crawler instructions cannot be an empty list.
`CRAWLER_INSTRUCTIONS_INVALID_ITEMS`	400	All items in crawler instructions must be JSON objects.

Instruction Errors

Error ID	HTTP Code	Description
`INSTRUCTION_INVALID_TYPE`	400	Instruction must be a JSON object.
`INSTRUCTION_ACTION_REQUIRED`	400	’action’ field is required.
`INSTRUCTION_ACTION_INVALID_TYPE`	400	’action’ must be a string.
`INSTRUCTION_ACTION_INVALID`	400	Invalid action (must be wait, click, mouse_click, send_keys, scroll_into_view).
`INSTRUCTION_SELECTOR_REQUIRED`	400	’selector’ or ‘xpath’ is required for the action.
`INSTRUCTION_SELECTOR_CONFLICT`	400	Cannot use both ‘selector’ and ‘xpath’ at the same time.
`INSTRUCTION_SELECTOR_INVALID_TYPE`	400	’selector’ must be a string.
`INSTRUCTION_XPATH_INVALID_TYPE`	400	’xpath’ must be a string.
`INSTRUCTION_TIMEOUT_INVALID_TYPE`	400	’timeout’ must be a number.
`INSTRUCTION_TIMEOUT_NEGATIVE`	400	’timeout’ cannot be negative.
`INSTRUCTION_TIMEOUT_TOO_HIGH`	400	’timeout’ cannot exceed 30 seconds.
`INSTRUCTION_INDEX_INVALID_TYPE`	400	’index’ must be an integer.
`INSTRUCTION_INDEX_NEGATIVE`	400	’index’ cannot be negative.
`INSTRUCTION_TEXT_REQUIRED`	400	’text’ field is required for ‘send_keys’ action.
`INSTRUCTION_TEXT_INVALID_TYPE`	400	’text’ must be a string.
`INSTRUCTION_TEXT_TOO_LONG`	400	’text’ must not exceed 1000 characters.
`INSTRUCTIONS_TOTAL_TIMEOUT_EXCEEDED`	400	Total timeout of all instructions exceeds maximum allowed (50s).

CAPTCHA Errors

Error ID	HTTP Code	Description
`INVALID_CAPTCHA_FIELDS`	400	Unrecognized fields provided in the captcha object.
`INVALID_CAPTCHA_TYPE`	400	Invalid captcha type. Must be RecaptchaV2, RecaptchaV3, or Turnstile.
`CAPTCHA_WEBSITE_URL_REQUIRED`	400	Captcha websiteURL is required.
`CAPTCHA_WEBSITE_URL_INVALID_TYPE`	400	Captcha websiteURL must be a string.
`CAPTCHA_WEBSITE_URL_INVALID_SCHEME`	400	Captcha websiteURL must start with http:// or https://.
`CAPTCHA_WEBSITE_URL_TOO_LONG`	400	Captcha websiteURL must not exceed 254 characters.
`CAPTCHA_WEBSITE_KEY_REQUIRED`	400	Captcha websiteKey is required.
`CAPTCHA_WEBSITE_KEY_INVALID_TYPE`	400	Captcha websiteKey must be a string.
`CAPTCHA_WEBSITE_KEY_TOO_SHORT`	400	Captcha websiteKey must be at least 10 characters.
`CAPTCHA_WEBSITE_KEY_TOO_LONG`	400	Captcha websiteKey must not exceed 200 characters.
`CAPTCHA_TYPE_REQUIRED`	400	Captcha type is required.
`CAPTCHA_TYPE_INVALID_TYPE`	400	Captcha type must be a string.

Options Errors

Error ID	HTTP Code	Description
`INVALID_OPTIONS_FIELDS`	400	Unrecognized fields provided in the options object.
`OPTIONS_USER_AGENT_INVALID_TYPE`	400	Options user_agent must be a string.
`OPTIONS_USER_AGENT_TOO_SHORT`	400	Options user_agent must be at least 10 characters.
`OPTIONS_USER_AGENT_TOO_LONG`	400	Options user_agent must not exceed 500 characters.
`OPTIONS_INVISIBLE_INVALID_TYPE`	400	Options invisible must be a boolean.
`OPTIONS_ENTERPRISE_INVALID_TYPE`	400	Options enterprise must be a boolean.
`OPTIONS_ACTION_INVALID_TYPE`	400	Options action must be a string.
`OPTIONS_ACTION_TOO_LONG`	400	Options action must not exceed 100 characters.

Proxy Errors

Error ID	HTTP Code	Description
`INVALID_PROXY_FIELDS`	400	Unrecognized fields provided in the proxy object.
`PROXY_SCHEME_REQUIRED`	400	Proxy scheme is required.
`PROXY_HOST_REQUIRED`	400	Proxy host is required.
`PROXY_PORT_REQUIRED`	400	Proxy port is required.
`PROXY_PASSWORD_REQUIRED`	400	Proxy password is required when username is provided.

Getting Started

Core Concepts

SDKs

MCP Server

CAPTCHA

Crawler

Detailed Error Codes

Authentication & Account Errors

General Request Errors

Crawler Errors

Instruction Errors

CAPTCHA Errors

Options Errors

Proxy Errors

Getting Started

Core Concepts

SDKs

MCP Server

CAPTCHA

Crawler

​Detailed Error Codes

​Authentication & Account Errors

​General Request Errors

​Crawler Errors

​Instruction Errors

​CAPTCHA Errors

​Options Errors

​Proxy Errors

Detailed Error Codes

Authentication & Account Errors

General Request Errors

Crawler Errors

Instruction Errors

CAPTCHA Errors

Options Errors

Proxy Errors