Your first error
The handful of responses you hit on a first Starkscan call — what each means and the exact fix.
Your first error
Almost every first-call problem is one of a few responses. Each has a clear fix. Get a key first with Get your first API key.
Quick triage
| Status | Meaning | Fix |
|---|---|---|
401 | Key missing or invalid | Send X-Starkscan-Api-Key: <your key> — no Bearer prefix. See Authentication. |
403 | Valid key, but the route or tier is not allowed | Use a route in your tier; batch / advanced-utility routes need a broader tier — see Advanced utilities. |
404 | Route or resource not found | Check the path shape /api/v1/{chain}/... (Base URLs and chains) and that the id exists. |
429 | Rate limit reached for the route class | Honor Retry-After; back off per X-Starkscan-Route-Class — see Rate limits. |
400 | API key sent under more than one header (code conflicting_api_key_headers) | Send it once, as X-Starkscan-Api-Key. |
400 | Malformed API key header value (code malformed_api_key_header) | Remove stray quotes or whitespace. |
The error envelope
{
"code": "rate_limited",
"message": "Rate limit exceeded; retry shortly",
"docSlug": "api/rate-limits",
"requestId": "mzk-..."
}Log requestId (also returned as X-Request-Id) whenever you report an issue.
Failure response examples
Every failure uses the same envelope with a stable code. The ones you hit first (the message text is illustrative — key off code, not the exact wording):
400 — key sent under more than one header
HTTP/1.1 400 Bad Request{
"code": "conflicting_api_key_headers",
"message": "API key supplied under multiple headers; send it once as X-Starkscan-Api-Key",
"requestId": "mzk-..."
}403 — valid key, route or tier not allowed
HTTP/1.1 403 Forbidden{
"code": "forbidden",
"message": "Key is valid but lacks the required route tier or scope",
"requestId": "mzk-..."
}429 — rate limit reached
HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-Starkscan-Route-Class: heavy{
"code": "rate_limited",
"message": "Rate limit exceeded; retry shortly",
"docSlug": "api/rate-limits",
"requestId": "mzk-..."
}Honor Retry-After (seconds) and keep backoff state per X-Starkscan-Route-Class, so a heavy limit does not stall cheap light reads.
Walkthroughs
401 — verify the header
The usual cause is a missing/typo'd header or a Bearer prefix (there is none). Use -i to inspect the response:
curl -i -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
"$STARKSCAN_BASE_URL/v1/$STARKSCAN_CHAIN/status"A 200 with chain status means auth is wired correctly.
404 — check the base path
Usually a wrong base path. The canonical /api-vs-/v1 rule lives in Base URLs and chains — confirm external calls use /api/v1/....
403 — wrong tier
The route is valid but not in your key's tier (often batch or advanced-utility routes). See Advanced utilities.
429 — back off by route class
Honor Retry-After and keep backoff state per X-Starkscan-Route-Class, so a heavy limit doesn't stop cheap light reads. See Rate limits.
Still stuck?
When you ask for help, include the host, the exact route, X-Request-Id, X-Starkscan-Route-Class, the status code, and a short response snippet. Never share your API key or any auth headers — redact them before sending logs.