> ## Documentation Index > Fetch the complete documentation index at: https://docs.scrapely.io/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Understand and handle API and SDK errors gracefully. 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. When using the REST API directly, errors are returned as a JSON object with an appropriate HTTP status code. ```json theme={null} { "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`. ```python theme={null} 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. |