Errors & rate limits
Error format, status codes, and the 429 / RateLimit headers.
Errors are JSON with a machine error code and a human message:
{ "error": "quota_exceeded", "message": "plan 'free' allows up to 1 active mint slot" }
Status codes
| Status | error | When |
|---|---|---|
| 400 | invalid_mint / invalid_query / invalid_body | Malformed mint, query param, or request body. |
| 401 | unauthorized | Missing key on a keyed route — or a presented x-api-key that is invalid/revoked, on any route (omit the key for anonymous access to public reads). |
| 402 | quota_exceeded / network_not_allowed | At your plan's slot ceiling, or plan can't use the network. |
| 404 | token_not_found / not_subscribed / not_found | Unknown mint, releasing a mint you don't hold, or an unknown /v1 path (same JSON envelope — never plain text). |
| 409 | slot_locked | Release blocked by the commitment lock — wait or pass ?rotate=true. |
| 429 | rate_limited | Per-plan throughput exceeded. Honour Retry-After + the RateLimit-* headers (below) and back off. |
| 503 | *_unavailable / service_unavailable | A datastore is briefly unreachable — retry. |
| 500 | internal | Unexpected error — retry; if it persists, contact support. |
Rate limits (429)
Every /v1/* request is metered by a token bucket: per tenant when authenticated (sized by your plan's rateRps / burst — see Plans) and per IP for anonymous browsing. When the bucket is empty the request is rejected with 429:
{ "error": "rate_limited", "message": "Rate limit exceeded for your plan. Retry in ~2s.", "retryAfter": 2, "plan": "builder" }
The limiter sets standard headers on every response (not just 429s), so you can pace requests pre-emptively rather than waiting to be throttled:
| Header | Meaning |
|---|---|
RateLimit-Limit | Your bucket's burst capacity. |
RateLimit-Remaining | Tokens left right now. |
RateLimit-Reset | Seconds until the bucket has a token again (when empty). |
Retry-After | Sent only on 429 — seconds to wait before retrying (mirrors retryAfter in the body). |
Client guidance — on a
429, sleep for Retry-After seconds (plus a little jitter) and retry; the call is idempotent for reads. Use RateLimit-Remaining to throttle before you hit the wall. Limits are best-effort and fail open — a brief limiter outage never blocks traffic.