Rate limiting

The API limits how many requests you can make in a rolling time window. Limits protect the service for everyone, so build your integration to stay within them and to back off when it is throttled.

The limits

Requests are counted in a fixed 60 second window. How many requests are allowed in that window depends on your Donorfy plan:

Plan	Requests per 60 seconds
Starter	50
Professional	100
Enterprise	200

Any tenant whose plan is not listed above is allowed the default of 100 requests per 60 seconds.

How requests are counted

The limit is applied per credential within a tenant, not per tenant as a whole and not per endpoint:

• System (Basic) authentication — counted per tenant code + permission name. Separate permission names therefore have separate allowances, and traffic from one integration does not consume another's.
• Access Identity (JWT) authentication — counted per tenant code + user.
• Unauthenticated requests — counted per caller IP address.

Every call to the API counts, including calls that fail validation or return an error.

When you exceed the limit

Once the allowance for the current window is used up, further requests are rejected with 429 Too Many Requests until the window rolls over. The response sets a Retry-After header containing the number of seconds to wait, and the body follows the standard error shape:

{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded. Please retry after the specified period.",
    "retryAfterSeconds": 60
  }
}

Staying within the limits

• Honour the Retry-After header rather than retrying immediately; add jitter if several workers may retry at once.
• Spread bulk work out over time instead of firing requests in a tight loop.
• Prefer paginated reads with a larger pageSize over many small requests — see API conventions.
• Cache data that changes rarely instead of re-fetching it on every operation.