Errors

Every error is JSON with a stable code and a human-readable message:

{ "code": "ip_not_allowed", "message": "this address may not use this key" }

Branch on code, never on message: messages can change at any time. New codes can be added within v1, so treat an unknown code by its HTTP status.

Error codes

Status	code	Meaning	What to do
400	invalid_request	A parameter is missing or invalid (for example a malformed contract or top above 50). Also sent with 405 for a wrong HTTP method.	Fix the request. Do not retry unchanged.
400	window_too_large	The window from since to until is longer than allowed (currently 31 days).	Ask for a shorter window, or split it into several calls.
401	invalid_key	The key is missing, malformed, unknown, expired or revoked, or your partner access is disabled.	Check the header format and the key. If it is correct, check its expiry date (/health shows it while the key works), or contact us.
403	ip_not_allowed	The request did not come from an address on the key’s allowlist.	Send us the server’s public egress IP. See IP allowlist.
403	scope_missing	The key does not have the scope this route needs.	Ask for the scope (for /hits: read:hits).
404	not_found	There is no such route.	Check the path and the base URL https://api.nimbusmint.bot/partner/v1.
429	rate_limited	Too many requests for this key, or for the API as a whole.	Wait Retry-After seconds. See Rate limits.
503	tenant_api_disabled	The partner API is switched off.	Retry later; contact us if it lasts.
503	ip_trust_unconfigured	The API cannot verify client addresses right now, so it refuses every request rather than guess.	Retry later; this is on our side.
503	internal	The API is temporarily unable to answer.	Retry after Retry-After seconds when sent, otherwise with backoff.

Authentication runs before routing, so a request without a valid key gets 401 invalid_key on every path, including paths that do not exist.

Why a 401 does not say more

Every key problem returns the same 401 invalid_key. Saying “unknown key” versus “wrong secret” versus “revoked” would help someone guessing keys, so the API never does. If you are sure the key is right, check its expiry date, then ask us: we can see why it failed.

Retrying

• Retry 429 and 503 after Retry-After seconds when it is sent, otherwise with exponential backoff (for example 1 s, 2 s, 4 s, capped at 60 s).
• Do not retry 400, 401, 403 or 404 without changing something first.
• In user-facing features such as a Discord command, fail soft: show your own data and skip NimbusMint’s rather than erroring.