Common Errors

Authentication

Send both X-API-Key and X-Project-Id, copied from the same project's API key settings. Use https://api.lexmount.com for COM projects and https://api.lexmount.cn for CN projects; the credentials must match the API region.

HTTP Status Guide

The extraction service accepts JSON bodies up to 1 MiB and rejects unknown fields. Exceeding its own decoder limit may produce 400 invalid_request; an earlier gateway can return 413. Keep request bodies small and pass URLs or snapshot IDs rather than inline HTML.

Error Response Shapes

Extraction-service failure:

{
  "request_id": "01964d0f-6abc-7f1b-9345-abcdef123456",
  "error": {
    "code": "http_status_not_ok",
    "message": "unexpected status code: 419",
    "stage": "fetch",
    "upstream_status_code": 419
  }
}

upstream_status_code is included when a target response status caused the failure. error.dom_id or metadata.dom_id, when present, can identify the captured page for reuse.

Gateway responses are not always the same shape. A project mismatch can return { "message": "projectID does not match consumer" }; an upstream failure can return { "error": "setaria_upstream_failed" }. Quota rejection uses an error object:

{
  "error": {
    "code": "webfetch_quota_exhausted",
    "message": "webfetch quota exhausted",
    "reason": "WEBFETCH_COUNT_EXHAUSTED"
  }
}

Check HTTP status first, then inspect error.code, a string error, or message as appropriate. Preserve the raw response if it is not JSON. Service responses carry request_id and X-Request-ID; early gateway rejections may not include the JSON field.

Frequent Cases

Credentials and Project ID

• 401: copy a current API key and use the endpoint for that project's region.
• 400 missing project: include X-Project-Id.
• 403 mismatch: the key and Project ID belong to different projects. Copy both from the same project's settings.

Quota or regional restriction

For 403 webfetch_quota_exhausted, check the selected project's Plans & Usage. Both extract and dump calls use Web Fetch allowance; a successful dump followed by successful extraction counts separately. Repeating the same request does not resolve exhausted allowance.

For client_ip_geo_blocked, check the service's regional availability and your regional endpoint. It is different from an API-key or quota error.

Invalid input

/v1/extract expects { "extract": { "url": "https://example.com" } }; /v1/dom/dump expects a top-level url. Extraction can use extract.dom_id instead. Use a public HTTP/HTTPS URL and only documented fields. Empty or unknown engine names, wrong JSON types, and the removed template_id option produce input errors.

Template or content failures

Enable trace.include_steps for extraction and inspect the page with Dump DOM. A missing template alone is not necessarily an error: the service can use generic extraction and queue template generation in the background. Check the actual error instead of assuming every 422 means “no template.”

A successful extraction may omit main_text or other optional fields. Check that the page contains the content you need; HTTP 200 does not guarantee extraction quality.

Fetch failures and timeouts

For http_fetch_failed, browser_fetch_failed, network_policy_blocked, or http_status_not_ok, check the URL, redirects, target accessibility, error.stage, and upstream_status_code when present. Web Fetch is for public pages; company-network access belongs to SDK local proxy.

Try an explicit engine through the documented options. Dump DOM can succeed while its top-level status_code is a target-site error; inspect the HTML and final URL. Retry transient 502/503/504 failures with bounded exponential backoff. A timeout does not prove that the server did no work or recorded no usage.

Snapshot failures

invalid_dom_id is an input error. dom_snapshot_not_found or a snapshot storage error can appear as 500 on extraction. Use the exact ID returned by the same regional service. If it is no longer available, fetch the original URL again rather than repeatedly submitting the missing ID.

Recommended Debug Flow

1. Check HTTP status and preserve the response body.
2. Resolve credentials, project mismatch, quota, or invalid input before retrying.
3. For extraction failures, enable trace.include_steps; request raw_dom only when needed.
4. Inspect status_code, final_url, and HTML from Dump DOM, then reuse its returned dom_id if available.
5. If the issue persists, provide support with the timestamp, endpoint, request ID when available, and a redacted payload/response. Remove API keys and confidential page content.