Common Errors

This page lists the most common HTTP-level and API-level failures when integrating with WebFetch.

Authentication

• The API is currently in internal testing
• External requests must include both X-API-Key and X-Project-Id
• Create or copy them from https://browser.lexmount.cn/settings/api-keys
• For overseas access, use https://browser.lexmount.com/settings/api-keys and replace the endpoint with https://api.lexmount.com

HTTP Status Guide

Common Error Response

{
  "error": {
    "code": "http_status_not_ok",
    "message": "unexpected status code: 419",
    "stage": "fetch",
    "upstream_status_code": 419
  }
}

upstream_status_code is present when the target server returned a non-accepted HTTP status. Other errors omit it.

Frequent Cases

401 unauthorized

Typical cause:

• missing X-API-Key
• invalid or expired test key

What to check:

• confirm the header name is exactly X-API-Key
• confirm the key value is correct
• confirm you are calling the public endpoint

400 missing project id

Typical cause:

• missing X-Project-Id
• using an API key from one project with a different project id

What to check:

• confirm the header name is exactly X-Project-Id
• confirm the project id was copied from the same API key settings page
• for overseas access, confirm you are calling https://api.lexmount.com

400 invalid_request

Typical cause:

• malformed JSON
• missing required fields
• wrong request shape for /v1/extract

What to check:

• /v1/extract expects an extract object
• at least one of extract.url or extract.dom_id is required
• /v1/dom/dump expects a top-level url

422 template or validation failures

Typical cause:

• no template matched
• extracted output did not pass validation
• target page content is not suitable for the current route or engine result

What to do:

• retry with the same URL and enable trace fields on /v1/extract
• use /v1/dom/dump to inspect the captured page HTML
• verify the target page is publicly accessible and contains meaningful content

502 fetch failures

Typical cause:

• target site blocked access
• target site returned a non-accepted HTTP status
• rendering failed
• browser-side fetch timed out

What to do:

• inspect error.upstream_status_code when it is present
• retry later
• test with /v1/dom/dump to inspect the actual captured result
• compare behavior across different URLs from the same site

500 internal server errors

Typical cause:

• unexpected service-side failure

What to do:

• keep the exact request payload
• record the full error body
• contact the service administrator with the failing URL and response

Recommended Debug Flow

1. Start with POST /v1/extract without trace options
2. If the request fails, inspect the HTTP status and error object
3. If needed, retry /v1/extract with trace.include_steps=true
4. If page content itself is suspicious, call POST /v1/dom/dump
5. Use the returned dom_id to retry extraction with extract.dom_id