Rate limits & IP allow-lists

Rate limits

Each key can make 300 requests a minute, unless CatholicPay gives it its own limit. Over the limit, requests are refused with 429 RATE_LIMITED and a Retry-After header (seconds): wait that long, then continue.

Some actions have their own limit: one withdrawal every 15 seconds per key (429 WITHDRAWAL_TOO_SOON).

To stay well inside the limits:

• Listen for webhooks instead of polling.
• Page with limit=200 when you read a lot.
• Spread batch work over time; use bulk transfers for many moves at once.

IP allow-lists

An admin can keep a key to a list of addresses, in the portal under Developers → Keys → Limit. From any other address the key is refused with 403 IP_NOT_ALLOWED. Use allow-lists on every key that can move money.