# Rate Limiting

Per-tenant fixed-window rate limits and how to handle 429 responses.

URL: https://docs.shiwake.app/docs/api/rate-limiting



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 [#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 [#429-responses]

When the limit is exceeded, further requests in the current window are
rejected with `429 Too Many Requests`:

```json
{
  "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 [#handling-429-in-clients]

Exponential backoff with jitter is the standard approach. The SDK does not
retry automatically; your application controls the retry policy.

<CodeBlockTabs defaultValue="csharp">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="csharp">
      C# (Polly)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bash">
      bash
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="csharp">
    ```csharp
    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));
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bash">
    ```bash
    # Simple retry loop with backoff
    attempt=0
    until curl -fsS -X POST "$URL" -H "$HEADERS" -d "$BODY"; do
      status=$?
      attempt=$((attempt + 1))
      if [ $attempt -ge 5 ]; then exit 1; fi
      sleep $((2 ** attempt))
    done
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="info">
  Retries are safe when you reuse the &#x2A;*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.
</Callout>

Why per-tenant and not per-key? [#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 [#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.
