Rate Limiting
Per-tenant fixed-window rate limits and how to handle 429 responses.
Shiwake applies a rate limit per tenant to protect the engine from
runaway clients and to keep one tenant's traffic from affecting another's.
The limit is applied as a fixed window and partitioned by the tenant id
resolved from the X-Api-Key header.
Limit
| Scope | Window | Requests | Queue |
|---|---|---|---|
| Per tenant | 1 minute | 200 | 0 (no queueing) |
Every call under /api/v1/ledger/* counts against the tenant's window.
Platform endpoints (/api/v1/platform/*) are not rate-limited. They are
used infrequently and by trusted operators.
The window is fixed, not sliding: it resets on the minute boundary. A
burst of 200 requests at 12:00:59 followed by another 200 at 12:01:00
will both succeed, even though that's 400 requests in two seconds.
429 responses
When the limit is exceeded, further requests in the current window are
rejected with 429 Too Many Requests:
{
"code": 429,
"message": "Too many requests.",
"data": null
}The response carries no custom retry headers: wait until the window rolls over (up to 60 seconds) and try again.
Handling 429 in clients
Exponential backoff with jitter is the standard approach. The SDK does not retry automatically; your application controls the retry policy.
using Polly;
using Polly.Retry;
var retry = new ResiliencePipelineBuilder()
.AddRetry(new RetryStrategyOptions
{
ShouldHandle = new PredicateBuilder()
.Handle<LedgerCoreException>(ex => ex.StatusCode == 429),
BackoffType = DelayBackoffType.Exponential,
UseJitter = true,
Delay = TimeSpan.FromSeconds(1),
MaxRetryAttempts = 4
})
.Build();
var entry = await retry.ExecuteAsync(
async ct => await ledger.PostJournalEntryAsync(request, idempotencyKey, ct));Retries are safe when you reuse the same Idempotency-Key on every
attempt. The engine will replay the original result if the first attempt
actually succeeded server-side. You will not double-post a journal entry
just because you retried after a 429.
Why per-tenant and not per-key?
API keys map one-to-one to tenants, so the effective behavior is the same. The partition is keyed on the tenant id (not the key string) so that key rotations do not reset the window.
Anticipating the limit
If you expect to exceed 200 req/min for legitimate reasons (bulk imports,
end-of-day reconciliation, backfills) batch your work. A single journal
entry can carry many balanced lines, so one POST /ledger/journal-entries
can move money between dozens of accounts in a single API call. Prefer
fewer, fatter requests over many thin ones.
Last updated on