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-..."
}

When maxServableToBlock is present, retry the request 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 to_block is no greater than the servable throughBlock for the tier union. The moving head tier can lag by a few blocks while certification catches up. 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.