Errors

Every error response on this API has the same shape:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly request quota exhausted.",
    "retry": true,
    "docs_url": "https://wellmarked.io/docs/guides/rate-limits",
    "upgrade_url": "https://wellmarked.io/billing",
    "retry_after": 1843
  }
}

retry_after (seconds) is present on 429.

The three agent fields

Most callers here are autonomous. They need to decide, without a human, whether to back off, change the request, or escalate. Three fields make that decision without parsing prose:

An error where retry is false will not become true by waiting. no_content, for example, is a fact about the page — an agent that retries it burns quota forever.

Every code

Rows marked ↑ in the retry column also carry an upgrade_url.

Handling them

Both official SDKs map these onto typed exceptions, so you can catch the class you care about rather than switching on strings. The exception carries code, status_code / statusCode, retry_after / retryAfter, retry_after_ms / retryAfterMs, and request_id / requestId.

import time
from wellmarked import WellMarked, RateLimitError, UnprocessableEntityError

with WellMarked(api_key="wm_...") as wm:
    try:
        result = wm.extract("https://example.com")
    except RateLimitError as e:
        # Branch on `code`, not the status — the two 429s need
        # completely different handling.
        if e.code == "rate_limit_too_fast":
            time.sleep(e.retry_after_ms / 1000)   # milliseconds
        else:
            escalate()                            # the month is spent
    except UnprocessableEntityError as e:
        # The page could not be extracted; e.code names why.
        ...