# Scrapfly Documentation ## Table of Contents ### Dashboard - [Intro](https://scrapfly.io/docs) - [Project](https://scrapfly.io/docs/project) - [Account](https://scrapfly.io/docs/account) - [Workspace & Team](https://scrapfly.io/docs/workspace-and-team) - [Billing](https://scrapfly.io/docs/billing) ### Products #### MCP Server - [Getting Started](https://scrapfly.io/docs/mcp/getting-started) - [Tools & API Spec](https://scrapfly.io/docs/mcp/tools) - [Authentication](https://scrapfly.io/docs/mcp/authentication) - [Examples & Use Cases](https://scrapfly.io/docs/mcp/examples) - [FAQ](https://scrapfly.io/docs/mcp/faq) ##### Integrations - [Overview](https://scrapfly.io/docs/mcp/integrations) - [Claude Desktop](https://scrapfly.io/docs/mcp/integrations/claude-desktop) - [Claude Code](https://scrapfly.io/docs/mcp/integrations/claude-code) - [ChatGPT](https://scrapfly.io/docs/mcp/integrations/chatgpt) - [Cursor](https://scrapfly.io/docs/mcp/integrations/cursor) - [Cline](https://scrapfly.io/docs/mcp/integrations/cline) - [Windsurf](https://scrapfly.io/docs/mcp/integrations/windsurf) - [Zed](https://scrapfly.io/docs/mcp/integrations/zed) - [Roo Code](https://scrapfly.io/docs/mcp/integrations/roo-code) - [VS Code](https://scrapfly.io/docs/mcp/integrations/vscode) - [LangChain](https://scrapfly.io/docs/mcp/integrations/langchain) - [LlamaIndex](https://scrapfly.io/docs/mcp/integrations/llamaindex) - [CrewAI](https://scrapfly.io/docs/mcp/integrations/crewai) - [OpenAI](https://scrapfly.io/docs/mcp/integrations/openai) - [n8n](https://scrapfly.io/docs/mcp/integrations/n8n) - [Make](https://scrapfly.io/docs/mcp/integrations/make) - [Zapier](https://scrapfly.io/docs/mcp/integrations/zapier) - [Vapi AI](https://scrapfly.io/docs/mcp/integrations/vapi) - [Agent Builder](https://scrapfly.io/docs/mcp/integrations/agent-builder) - [Custom Client](https://scrapfly.io/docs/mcp/integrations/custom-client) #### Web Scraping API - [Getting Started](https://scrapfly.io/docs/scrape-api/getting-started) - [API Specification]() - [Monitoring](https://scrapfly.io/docs/monitoring) - [Customize Request](https://scrapfly.io/docs/scrape-api/custom) - [Debug](https://scrapfly.io/docs/scrape-api/debug) - [Unblocker (formerly ASP)](https://scrapfly.io/docs/scrape-api/unblocker) - [Proxy](https://scrapfly.io/docs/scrape-api/proxy) - [Proxy Mode](https://scrapfly.io/docs/scrape-api/proxy-mode) - [Proxy Mode - Screaming Frog](https://scrapfly.io/docs/scrape-api/proxy-mode/screaming-frog) - [Proxy Mode - Apify](https://scrapfly.io/docs/scrape-api/proxy-mode/apify) - [(Auto) Data Extraction](https://scrapfly.io/docs/scrape-api/extraction) - [Javascript Rendering](https://scrapfly.io/docs/scrape-api/javascript-rendering) - [Javascript Scenario](https://scrapfly.io/docs/scrape-api/javascript-scenario) - [SSL](https://scrapfly.io/docs/scrape-api/ssl) - [DNS](https://scrapfly.io/docs/scrape-api/dns) - [Cache](https://scrapfly.io/docs/scrape-api/cache) - [Batch (Multi-URL Scraping)](https://scrapfly.io/docs/scrape-api/batch) - [Session](https://scrapfly.io/docs/scrape-api/session) - [Webhook](https://scrapfly.io/docs/scrape-api/webhook) - [Schedule](https://scrapfly.io/docs/scrape-api/schedule) - [Screenshot](https://scrapfly.io/docs/scrape-api/screenshot) - [Errors](https://scrapfly.io/docs/scrape-api/errors) - [Timeout](https://scrapfly.io/docs/scrape-api/understand-timeout) - [Throttling](https://scrapfly.io/docs/throttling) - [Troubleshoot](https://scrapfly.io/docs/scrape-api/troubleshoot) - [Billing](https://scrapfly.io/docs/scrape-api/billing) - [FAQ](https://scrapfly.io/docs/scrape-api/faq) #### Crawler API - [Getting Started](https://scrapfly.io/docs/crawler-api/getting-started) - [API Specification]() - [Retrieving Results](https://scrapfly.io/docs/crawler-api/results) - [WARC Format](https://scrapfly.io/docs/crawler-api/warc-format) - [Data Extraction](https://scrapfly.io/docs/crawler-api/extraction-rules) - [Search](https://scrapfly.io/docs/crawler-api/search) - [Prompt & Extract](https://scrapfly.io/docs/crawler-api/prompt) - [Auto Refresh](https://scrapfly.io/docs/crawler-api/refresh) - [Webhook](https://scrapfly.io/docs/crawler-api/webhook) - [Schedule](https://scrapfly.io/docs/crawler-api/schedule) - [Billing](https://scrapfly.io/docs/crawler-api/billing) - [Errors](https://scrapfly.io/docs/crawler-api/errors) - [Troubleshoot](https://scrapfly.io/docs/crawler-api/troubleshoot) - [FAQ](https://scrapfly.io/docs/crawler-api/faq) #### Screenshot API - [Getting Started](https://scrapfly.io/docs/screenshot-api/getting-started) - [API Specification]() - [Accessibility Testing](https://scrapfly.io/docs/screenshot-api/accessibility) - [Webhook](https://scrapfly.io/docs/screenshot-api/webhook) - [Schedule](https://scrapfly.io/docs/screenshot-api/schedule) - [Billing](https://scrapfly.io/docs/screenshot-api/billing) - [Errors](https://scrapfly.io/docs/screenshot-api/errors) #### Extraction API - [Getting Started](https://scrapfly.io/docs/extraction-api/getting-started) - [API Specification]() - [Rules Template](https://scrapfly.io/docs/extraction-api/rules-and-template) - [LLM Extraction](https://scrapfly.io/docs/extraction-api/llm-prompt) - [AI Auto Extraction](https://scrapfly.io/docs/extraction-api/automatic-ai) - [Webhook](https://scrapfly.io/docs/extraction-api/webhook) - [Billing](https://scrapfly.io/docs/extraction-api/billing) - [Errors](https://scrapfly.io/docs/extraction-api/errors) - [FAQ](https://scrapfly.io/docs/extraction-api/faq) #### Data API #### Proxy Saver - [Getting Started](https://scrapfly.io/docs/proxy-saver/getting-started) - [Fingerprints](https://scrapfly.io/docs/proxy-saver/fingerprints) - [Optimizations](https://scrapfly.io/docs/proxy-saver/optimizations) - [SSL Certificates](https://scrapfly.io/docs/proxy-saver/certificates) - [Protocols](https://scrapfly.io/docs/proxy-saver/protocols) - [Pacfile](https://scrapfly.io/docs/proxy-saver/pacfile) - [Secure Credentials](https://scrapfly.io/docs/proxy-saver/security) - [Billing](https://scrapfly.io/docs/proxy-saver/billing) #### Cloud Browser API - [Getting Started](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Proxy & Geo-Targeting](https://scrapfly.io/docs/cloud-browser-api/proxy) - [Unblock API](https://scrapfly.io/docs/cloud-browser-api/unblock) - [Captcha Solver](https://scrapfly.io/docs/cloud-browser-api/captcha-solver) - [File Downloads](https://scrapfly.io/docs/cloud-browser-api/file-downloads) - [Session Resume](https://scrapfly.io/docs/cloud-browser-api/session-resume) - [Human-in-the-Loop](https://scrapfly.io/docs/cloud-browser-api/human-in-the-loop) - [Debug Mode](https://scrapfly.io/docs/cloud-browser-api/debug-mode) - [Browser Extensions](https://scrapfly.io/docs/cloud-browser-api/extensions) - [Native Browser MCP](https://scrapfly.io/docs/cloud-browser-api/mcp) - [DevTools Protocol](https://scrapfly.io/docs/cloud-browser-api/cdp-reference) ##### Integrations - [Puppeteer](https://scrapfly.io/docs/cloud-browser-api/puppeteer) - [Playwright](https://scrapfly.io/docs/cloud-browser-api/playwright) - [Selenium](https://scrapfly.io/docs/cloud-browser-api/selenium) - [Vercel Agent Browser](https://scrapfly.io/docs/cloud-browser-api/agent-browser) - [Browser Use](https://scrapfly.io/docs/cloud-browser-api/browser-use) - [Stagehand](https://scrapfly.io/docs/cloud-browser-api/stagehand) - [Billing](https://scrapfly.io/docs/cloud-browser-api/billing) - [Errors](https://scrapfly.io/docs/cloud-browser-api/errors) ### Tools - [Antibot Detector](https://scrapfly.io/docs/tools/antibot-detector) ### SDK - [Golang](https://scrapfly.io/docs/sdk/golang) - [Python](https://scrapfly.io/docs/sdk/python) - [Rust](https://scrapfly.io/docs/sdk/rust) - [TypeScript](https://scrapfly.io/docs/sdk/typescript) - [Scrapy](https://scrapfly.io/docs/sdk/scrapy) ### Integrations - [Getting Started](https://scrapfly.io/docs/integration/getting-started) - [LangChain](https://scrapfly.io/docs/integration/langchain) - [LlamaIndex](https://scrapfly.io/docs/integration/llamaindex) - [CrewAI](https://scrapfly.io/docs/integration/crewai) - [Zapier](https://scrapfly.io/docs/integration/zapier) - [Make](https://scrapfly.io/docs/integration/make) - [n8n](https://scrapfly.io/docs/integration/n8n) ### Academy - [Overview](https://scrapfly.io/academy) - [Web Scraping Overview](https://scrapfly.io/academy/scraping-overview) - [Tools](https://scrapfly.io/academy/tools-overview) - [Reverse Engineering](https://scrapfly.io/academy/reverse-engineering) - [Static Scraping](https://scrapfly.io/academy/static-scraping) - [HTML Parsing](https://scrapfly.io/academy/html-parsing) - [Dynamic Scraping](https://scrapfly.io/academy/dynamic-scraping) - [Hidden API Scraping](https://scrapfly.io/academy/hidden-api-scraping) - [Headless Browsers](https://scrapfly.io/academy/headless-browsers) - [Hidden Web Data](https://scrapfly.io/academy/hidden-web-data) - [JSON Parsing](https://scrapfly.io/academy/json-parsing) - [Data Processing](https://scrapfly.io/academy/data-processing) - [Scaling](https://scrapfly.io/academy/scaling) - [Walkthrough Summary](https://scrapfly.io/academy/walkthrough-summary) - [Scraper Blocking](https://scrapfly.io/academy/scraper-blocking) - [Proxies](https://scrapfly.io/academy/proxies) --- # Error Reference All errors returned by the Alerting API use the `ERR::ALERT::*` prefix. Each error includes an HTTP status code, a machine-readable code, and a description. The full error catalog is also available at `GET /doc/errors` on the Scrapfly API and in the [error documentation](https://scrapfly.io/docs/scrape-api/errors) shared across all products. | Error code | HTTP status | Retryable | Description & what to do | |---|---|---|---| | `ERR::ALERT::UNKNOWN_METRIC` | 400 | No | The `metric_id` you provided is not in the alertable metric registry. Metric IDs are case-sensitive. **Fix:** Call `GET /alert/metric-families` or check the [metric reference](https://scrapfly.io/docs/alerting/metric-reference) for the full list of valid IDs. | | `ERR::ALERT::INVALID_DIMENSIONS` | 400 | No | One or more keys in `metric_dimensions` are not in the chosen metric's `allowed_dimensions` list, or `metric_dimensions` is not a JSON object of string key/value pairs. Only the keys are checked; dimension values are passed through to the query as filters. **Fix:** Check the [dimension values reference](https://scrapfly.io/docs/alerting/metric-reference#dimension-values) and remove unknown keys. | | `ERR::ALERT::INVALID_THRESHOLD` | 400 | No | The `threshold` value or `comparator` is invalid. `threshold` must be a finite number (not NaN or Infinity). `comparator` must be one of: `gt`, `lt`, `gte`, `lte`, `eq`, `neq`. **Fix:** Pass a numeric threshold and a valid comparator string. | | `ERR::ALERT::INVALID_SUSTAINED_WINDOW` | 400 | No | `sustained_minutes` is out of range. It must be between 1 and 1440 (1 day). Setting it to 0 or a negative number is not allowed. **Fix:** Use a value between 1 and 1440. The registry default for most metrics is 5 minutes; start there. | | `ERR::ALERT::CHANNEL_UNREACHABLE` | 400 / 502 | No | The `notify_channels` list is unusable. This happens when: - `notify_channels` is empty. At least one channel is required. - `kind` is not one of `email`, `webhook`, or `inapp`. Returned as 400 when create/update validation rejects the channel list. The test-fire endpoint returns 502 instead when a configured channel cannot be delivered to. **Fix:** Check that `notify_channels` has at least one entry and that every entry has a valid `kind`. | | `ERR::ALERT::PROJECT_NOT_FOUND` | 400 / 403 | No | The `project_uuid` does not exist or is not accessible with the authenticated account. Returned as 400 when the request carries no project context, and as 403 when the authenticated account does not own the supplied `project_uuid`. **Fix:** Verify the project UUID in your [Projects dashboard](https://scrapfly.io/dashboard/project). If you are using an API key, confirm it belongs to an account that has access to the project. | | `ERR::ALERT::NOT_FOUND` | 401 / 404 | No | Returned as 404 when the `alert_uuid` does not exist, was deleted, or does not belong to the authenticated account, and as 401 when the request carries no authenticated user at all. **Fix:** Use `GET /alert?project_uuid=…` to list alerts and confirm the UUID. | | `ERR::ALERT::EVAL_TIMEOUT` | 504 | Yes | The evaluation query timed out. The alert state was not changed; the next scheduled tick will retry automatically. This appears in the alert's event log as an evaluation-error entry. **Action:** No action needed for one-off timeouts. If this error appears repeatedly for the same alert, the evaluation window may be too wide for the metric's data volume. Try narrowing the sustained window or contact support. | | `ERR::ALERT::INTERNAL` | 500 | Yes | A generic server-side error during a create / read / update / delete operation. The `reason` field of the error envelope carries the operation context (for example *"create alert failed"* or *"list alerts failed"*). **Action:** Retry the request. Mutations are rolled back on failure, so retrying after a partial error is safe. If the error persists for several minutes, [contact support](https://scrapfly.io/contact). | ## Error response shape Most Alerting API errors (every authentication, ownership, validation and channel failure on the CRUD endpoints) answer with a single `error` key carrying the code: ``` { "error": "ERR::ALERT::NOT_FOUND" } ``` Validation failures append the offending detail to that same key, e.g. `ERR::ALERT::UNKNOWN_METRIC: metric_id "foo" is not a registered metric`. Only `ERR::ALERT::INTERNAL` and the metric query endpoints (`/alert/preview`, `/alert/{alert_uuid}/series`) use the full Scrapfly API error envelope: ``` { "code": "ERR::ALERT::UNKNOWN_METRIC", "reason": "the metric this rule points at is not registered", "message": "The metric_id provided is not a registered alertable metric. Call GET /alert/metric-families for the full list of supported metrics.", "retryable": false, "error_id": "a8eab7ea-3836-48cc-89ae-5f06facc0e33", "http_code": 400, "links": { "Related Error Doc": "https://scrapfly.io/docs/alerting/error/ERR::ALERT::UNKNOWN_METRIC", "Alert Documentation": "https://scrapfly.io/docs/alerting" } } ``` The `message` field is copied verbatim from the error catalog, so it is identical for every occurrence of a given code; `reason` carries the per-request context. Two request-level failures use neither shape. A body that does not parse answers `{"error": "invalid request body", "details": "..."}`, where `error` is a plain sentence and not an `ERR::` code. A request that omits the alert UUID from its path answers the generic envelope: `reason`, `message`, `error_id` and `http_code`, with no `code` field and no `error` key. [ Webhook Payload ](https://scrapfly.io/docs/alerting/webhook-payload) [ Anti-Spam Controls ](https://scrapfly.io/docs/alerting/anti-spam)