Error Codes Reference

The target site detected and blocked the scraping attempt. All tier escalations failed.

Solution: Try using max_tier: "4" to enable CAPTCHA solving, or contact support for sites with advanced protection.

A bot detection challenge (anti-bot wall, reCAPTCHA, hCaptcha) was encountered.

Solution: Enable JavaScript rendering with mode: "js" or increase max tier.

The scraping operation timed out before completing.

Solution: Increase timeout parameter or use async mode with polling.

The page content exceeds the 10MB size limit.

Solution: Target a specific section of the page or use a different scraping strategy.

The URL returns a content type not supported by the selected mode.

Solution: Use the appropriate mode - pdf for PDFs, ocr for images.

Content was fetched but could not be parsed or extracted.

Solution: Check if the URL returns valid HTML/content. Try a different extraction mode.

The page requires authentication to access.

Solution: This URL is behind a login wall and cannot be scraped without credentials.

The content is behind a paywall and requires subscription to access.

Solution: Content requires paid subscription. Cannot be accessed via scraping.

Network connection failed - DNS error, connection refused, or SSL error.

Solution: Verify the URL is valid and the site is online. Retry after a brief delay.

The request sets advanced.render_js: true together with a cost_controls.max_tier below "4". Browser rendering runs on tier 4, so the request is rejected at submission on /api/v1/scrape, /api/v1/batch items, and /api/v1/crawl, before any balance is reserved or charged. In production the response body is {"detail": "Invalid request parameters"}.

Solution: Set max_tier to "4", omit it, or use render_js: "auto", which lets AlterLab decide when browser rendering is needed. Do not retry the same request unchanged.

When a request forces browser rendering (advanced.render_js: true or cost_controls.force_tier: "4") and the job fails because the page returned a verification challenge or did not finish loading in time, the error object includes a hint. It appears on the synchronous 422 response, on GET /api/v1/jobs/{job_id}, and on failed crawl pages. Successful jobs and jobs that do not force rendering never include it. Existing fields and status codes are unchanged.

{
  "detail": "anti_bot_blocked: ...",
  "error": {
    "error_code": "anti_bot_blocked",
    "message": "...",
    "protection_type": "cloudflare",
    "hint": {
      "code": "render_js_auto",
      "reason": "challenge",
      "message": "This request forced browser rendering and the page returned a verification screen instead of content. Retrying with render_js=\"auto\" lets the platform start at the lowest tier that returns the page, which succeeds more often for requests like this one."
    }
  }
}

Fields: code is always render_js_auto; reason is challenge or timeout; message is human-readable guidance.

Solution: Retry with render_js: "auto" (and without force_tier) so AlterLab starts at the lowest tier that returns the page.

The API key provided is invalid, malformed, or has been revoked.

Solution: Check that your API key starts with sk_live_ or sk_test_ and is active in your dashboard.

No API key was provided in the request headers.

Solution: Include the X-API-Key header with your API key.

The session token (for dashboard APIs) has expired.

Solution: Log in again to get a fresh session token.

API-key verification is briefly at capacity. The key itself is valid: this is returned instead of 401 so clients do not treat a load spike as a revoked key. The response carries a Retry-After header. WebSocket connections are closed with code 1013 (Try Again Later) in the same situation.

Solution: Retry after the number of seconds in the Retry-After header. Do not rotate or disable the key. The official SDKs retry automatically.

The provided session_id does not exist or belongs to another user.

Solution: Verify the UUID. Use GET /sessions to list your valid sessions.

The session cookies have expired or the session was marked as expired after repeated validation failures.

Solution: Log in to the target site again and call POST /sessions/:id/refresh with fresh cookies.

The scrape URL domain does not match the session's stored domain. For example, using an amazon.com session to scrape walmart.com.

Solution: Create a separate session for each target domain.

The session has been deleted or disabled.

Solution: Create a new session with fresh cookies.

Maximum number of sessions per account (50) has been reached.

Solution: Delete unused or expired sessions. Use GET /sessions?status=expired to find candidates for cleanup.

Both session_id and cookies were provided in the scrape request. These parameters are mutually exclusive.

Solution: Use either session_id (for stored sessions) or cookies (for inline one-off use), not both.

Your account has insufficient balance to complete this request.

Solution: Check your balance with GET /api/v1/usage and upgrade your plan or add funds.

The estimated cost exceeds your max_credits limit.

Solution: Increase max_credits or use a simpler scraping mode.

Your subscription has been cancelled or payment failed.

Solution: Check your billing status in the dashboard and update payment method if needed.

The request uses an organization API key (member or service account), but the organization has no active owner to bill. No personal wallet is charged instead. Not retryable.

Solution: An organization administrator must assign an active owner. The error is returned in detail.error with a readable detail.message.

The organization billing account could not be resolved for this request. The request is rejected rather than billed to the wrong account.

Solution: Retry after the number of seconds in the Retry-After header.