Skip to main content
The Dolfin API is rate limited. Requests over the limit are rejected with HTTP 429 Too Many Requests and no work is performed — a rejected request never partially applies.

​
The limit that applies to every endpoint

This covers every endpoint, on every path, whether authenticated or public. Sustained abuse is treated more harshly: an IP exceeding 600 requests in 60 seconds is blocked for 10 minutes, and every request during that period returns 429.
Limits are scoped by source IP, not by API key or organisation. If you call Dolfin from a server with a single egress IP, every organisation you serve shares one 120 req/min budget. Plan capacity against your total request volume across all tenants, not per tenant.If you run behind NAT or a shared gateway, unrelated traffic from the same address counts toward your budget too. A dedicated egress IP is the reliable way to get a predictable budget.

​
Additional limits on specific endpoints

Some endpoints carry a second, narrower limit on top of the 120 req/min above. Where both apply, whichever is reached first rejects the request.
The authentication limit is deliberately strict and is shared across all callers, not per client. Exchange your credentials for a token once and reuse it for the token’s lifetime rather than authenticating per request — see Authentication.

​
Handling a 429

A rejected request returns status 429 with an empty body.
429 responses do not include a Retry-After header, and unlike other Dolfin errors they do not carry a machine-readable code field. Switch on the HTTP status code alone.
Because every window is a fixed 60 seconds, you do not need a header to recover correctly:
  • Throttled at 120 req/min — wait until the current minute elapses. Waiting a full 60 seconds always clears it.
  • Blocked after sustained abuse — wait 10 minutes. Retrying sooner will not succeed and extends the pattern that triggered the block.
Recommended client behaviour:
Jitter matters: if you batch work across many tenants, a fixed retry delay makes every worker retry in the same instant and re-trip the limit.

​
Staying under the limits

  • Use pagination rather than polling. List endpoints return a cursor; page through results instead of re-requesting the collection.
  • Use webhooks instead of polling for state changes. Waiting for bill.approved costs nothing; polling a bill every few seconds until it changes is the most common way integrations hit the limit.
  • Batch overnight work with a delay between requests. 120 req/min is two per second sustained; a bulk import should pace itself rather than burst.
  • Reuse tokens. Re-authenticating per request will hit the auth limit long before the general one.

​
Requesting a higher limit

If your integration legitimately needs more than 120 requests per minute, contact your Dolfin representative with your expected peak volume and the egress IPs you call from.