Rate limits

To protect the platform and your church, the API has rate limits. Exceed them and you get 429 Too Many Requests.

Per-plan quotas

> Burst = instantaneous peak allowed over the average.

Per-endpoint limits

Some endpoints have a stricter dedicated quota:

Response headers

Each response includes:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1714165800     (Unix timestamp in seconds)
X-RateLimit-Bucket: minute

When you get 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 18

Retry-After says how many seconds to wait before the next attempt.

Recommended strategy

import time, requests
 
def call(url):
    for attempt in range(5):
        r = requests.get(url, headers={...})
        if r.status_code != 429:
            return r
        wait = int(r.headers.get('Retry-After', 2 ** attempt))
        time.sleep(wait)
    raise Exception("Rate limit exceeded after 5 attempts")

How rate limit counts

The bucket is per (token, window). That means:

• Token A and token B have independent buckets.
• But if both share the same X-Tenant, both also count against the tenant quota.
• So we recommend one service token per integration, not sharing.

Suggestions

1. Bulk endpoints: when available, prefer them to 1000 singular calls (POST /v1/members/bulk allows up to 500 per call).
2. Webhooks vs polling: if your case is “tell me when X happens”, subscribe to the webhook instead of polling.
3. ETag for cache: saves quota when data doesn’t change (HTTP 304 doesn’t count against the data limit, only requests).
4. Wide pagination: limit=250 better than 5 calls of limit=50.
5. Off-hours batch: if you have a batch job (nightly export), run it at 03:00-05:00 main-campus time — lowest-usage windows.

Outbound webhook quotas

Ministrium sends webhooks to your church’s endpoints. If your endpoint is slow (>3 s) or fails, there’s backoff:

• Retry 1: in 30 s
• Retry 2: in 5 min
• Retry 3: in 1 h
• Retry 4: in 6 h
• Retry 5: in 24 h
• After 5 failures: webhook is disabled, email to org_admin.

Keep your endpoint fast (respond 2xx < 200 ms and process async).