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 X-API-Key
• Contact an administrator to get your API key

HTTP Status Guide

Common Error Response

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid X-API-Key",
    "stage": "auth"
  }
}

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 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
• rendering failed
• browser-side fetch timed out

What to do:

• 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 and keep trace.include_steps=false
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