Skip to main content

Rate Limiting

There is no blanket rate limit on this API. A route is limited only where it says so, and the limits differ by surface. The table below is the complete list.

The limits

Cache your token. The token endpoint’s allowance is four requests per window, and tokens are valid for 60 minutes. A client that fetches a fresh token per API call will start receiving 429s within seconds. Request a new one only when the current one is close to expiring.

What “per organization” means, and why it is not per IP

Agency limits are counted against your organization, not your IP address. Two consequences, both intentional:
  • Several servers sharing one Turris organization share one allowance. Scaling your fleet horizontally does not multiply your quota.
  • Several organizations behind one corporate NAT do not throttle each other.
The carrier limits on the two routes above are counted per caller in the ordinary way.

Allowances are per endpoint, not per surface

The route is part of what a limit is counted against, so each endpoint carries its own 120 or its own 30. Listing producers does not consume the allowance for listing documents. That is deliberate: the failure a write limit guards against is a runaway loop against one endpoint, which a per-route bucket catches exactly as well as a shared one — while a shared bucket would let a bulk producer import starve an unrelated document upload.

Response headers

Every throttled response carries the state of its bucket:

When you exceed a limit

Branch on errorType, never on the message text.

Retry strategy

Read Retry-After when it is present and wait that long. Fall back to exponential backoff when it is not.
Retrying a write after a 429 is safe only if you send the same Idempotency-Key you sent the first time. A throttled request may or may not have been processed before the limit was applied. See Idempotency.

If a limit is wrong for your integration

These numbers are sized for interactive and scheduled use, not for a bulk backfill. If you have a legitimate case that does not fit — a one-off migration, a nightly full sync of a large group — tell us at support@turrisfi.com rather than working around it with parallel credentials.