Rate limits
How Tanitar limits request rates per plan, rate class and API key, and how to handle a 429.
Tanitar limits how fast each API key can call the APIs. The limits come from your plan, so they are the same across every API and change only when your plan does.
How limits work
- Rate classes. Every route belongs to a rate class:
readfor routes that only read, andmutationfor routes that change state. Each class has its own budget, so heavy reading never uses up your ability to write. - Per plan. Your plan's numeric limits set, for each class, how many requests are allowed and over what window.
- Per API key. Budgets are counted per account and per credential. Each of your API keys has its own budget; spreading one workload over several keys does not change what each key may do.
- Sliding window. The window moves with time: a request is admitted if fewer than the limit were admitted in the preceding window, so capacity returns gradually rather than all at once at a fixed boundary.
The default plan
The default plan allows:
| Rate class | Requests | Window |
|---|---|---|
read | 120 | 60 seconds |
mutation | 30 | 60 seconds |
Your plan may differ; ask Tanitar for the limits on your account.
Every request that passes the key and scope checks counts, including a retry that returns a stored idempotent outcome, and a request that is then refused for another reason, such as validation or a missing resource.
When you are limited
A request over the limit is refused with 429 and the standard error envelope:
{
"success": false,
"statusCode": 429,
"responseType": "TOO_MANY_REQUESTS",
"errorCode": "ACCESS_RATE_LIMITED",
"message": "Too Many Requests",
"data": null,
"requestId": "0d7c5b1a-2e4f-4a8b-9c3d-6e1f2a3b4c5d",
"timestamp": "2026-09-30T10:04:11.920Z"
}The response carries no Retry-After header and no remaining-quota headers. Back off
exponentially instead:
- Wait a short base delay (for example 1 second), plus random jitter.
- Double the delay on each consecutive
429, up to a ceiling of about one window (60 seconds on the default plan). - Reset the delay after a request succeeds.
For mutations, retry with the same Idempotency-Key, so a request that was in fact applied is
not applied twice.
The Identity, Game and Reward APIs also absorb short bursts from a single client: more than two
requests within 100 milliseconds can be answered 429 with responseType TOO_MANY_REQUESTS and
no errorCode. The same back-off handles it; pacing your calls avoids it.
Other refusals to retry
If the service that keeps rate-limit counters is unavailable, Tanitar refuses the request with
503 and ACCESS_STATE_UNAVAILABLE rather than let it through unmetered. Treat it like a 429:
back off and retry.
Staying within your limits
- Cache reads you repeat: the currency registry, published listings, the mission catalog.
- Subscribe to webhooks instead of polling for changes.
- Use cursors and page sizes up to the maximum when reading long lists. See pagination.
- Give independent workloads separate API keys so one cannot starve another.