Retryable API errors

Starkscan uses HTTP 503 when a request is valid but a bounded serving dependency is temporarily unavailable. The response body keeps the standard REST error shape:

{
  "code": "event_key_index_coverage_unavailable",
  "message": "to_block 13978045 exceeds certified coverage for this selector/key position. Highest servable to_block is 13977799.",
  "maxServableToBlock": 13977799,
  "docSlug": "api/retry",
  "requestId": "mzk-..."
}

For an entitled positional full-range event request, Starkscan now performs this upper-bound clamp itself and returns HTTP 200; compare rangeCoverage.requestedToBlock with rangeCoverage.completeThroughBlock. Older deployments and requests without a complete prefix can still return this typed 503. When maxServableToBlock is present there, retry once with to_block clamped to that exact value. Use Retry-After only when you need the original higher bound. Do not retry immediately in a tight loop, and do not treat a 503 as an empty result or as proof that an address, event, holder, or balance is absent.

For full-range positional event searches, first read /v1/meta/capabilities. A wide request is eligible only when eventSearch.fullRange.selectorCoverage contains ready coverage for the exact selector and key position, and the requested lower bound is no lower than servableFromBlock. maxServableToBlock is the complete response ceiling; throughBlock is a legacy safe compatibility bound, and tierCertifiedThroughBlock is the actual tier certificate diagnostic. The server can bridge a small moving-head certification lag with a bounded raw head-tail scan while preserving complete cursor pagination. If a request still reaches an uncovered selector/key prefix, prefer the response's maxServableToBlock over re-reading capabilities: it is the highest bound proved for that exact failed request.

If the response code is full_range_selector_not_supported, retrying the same request will not help until capabilities advertise support for that selector and position. If the response is rate_limited, follow the rate limit guide instead.

Token-holder policy states

For token-holder routes, 422 with code="unqualified_token_policy" is a terminal policy-review result: the token has no current explicit address-keyed holder policy. It has no Retry-After; do not retry it, treat it as an empty holder population, or trigger a client-side scan or RPC fallback.

This differs from a qualified token's intentionally redacted 200 response and from an eligible token's temporary 503, which remains retryable and honors Retry-After. Read Token holders and /v1/meta/capabilities before selecting a token-holder workflow; discovery in the broader token universe does not itself make a token eligible.