Rate limits
Understand Starkscan route-class budgets, headers, and the correct retry behavior for external API keys.
Loading documentation content…
Understand Starkscan route-class budgets, headers, and the correct retry behavior for external API keys.
Starkscan rate-limits external API keys by route class.
Treat rate limits as part of the HTTP contract, not as a hidden operational detail.
Current external keys use two public route classes:
| Class | Typical use | Example routes |
|---|---|---|
light | cheap health-style reads | GET /v1/{chain}/status |
heavy | higher-cost entity reads, traces, search, contract reads, and batch helpers | GET /v1/{chain}/tx/{tx_hash}/trace, GET /v1/{chain}/search, GET /v1/{chain}/contract/{address}/read, POST /v1/{chain}/tx/previews |
The exact numeric budget is deployment-controlled. Read the headers instead of hard-coding assumptions into clients.
Starkscan can emit these budget headers on budgeted responses:
x-ratelimit-limitx-ratelimit-remainingx-ratelimit-policyX-Mezcal-Route-ClassOn 429 Too Many Requests, Starkscan also emits:
Retry-AfterExample response headers:
x-ratelimit-limit: 30
x-ratelimit-remaining: 0
x-ratelimit-policy: heavy;w=60
X-Mezcal-Route-Class: heavy
retry-after: 12429 Too Many Requests, stop and honor Retry-After.x-ratelimit-remaining still looks healthy.429curl -i \
-H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/contract/<address>/read?selector=<selector>"Representative response:
HTTP/1.1 429 Too Many Requests
retry-after: 12
x-ratelimit-limit: 30
x-ratelimit-remaining: 0
x-ratelimit-policy: heavy;w=60
X-Mezcal-Route-Class: heavy
content-type: application/json; charset=utf-8
{"code":"rate_limited","message":"Rate limit exceeded; retry shortly","docSlug":"api/rate-limits","requestId":"mzk-..."}Current public-read rate limiting is process-local fixed-window state:
Do not build client correctness on an assumption that every host behaves like one perfectly global distributed limiter.
heavy 429 should not force an agent to stop cheap light status checks.X-Request-Id on every failure.