ShiwakeDocs

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

ScopeWindowRequestsQueue
Per tenant1 minute2000 (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.

Edit on GitHub

Last updated on

On this page