Rate Limits
To ensure stability for all users, VRP Billing enforces per-endpoint rate limits. When you exceed a limit the API returns 429 Too Many Requests with headers describing when you can retry.
Headers
| Header | Description |
|---|---|
X-RateLimit-Limit |
Maximum number of requests allowed in the current window. |
X-RateLimit-Remaining |
Requests remaining before the limit is reached. |
X-RateLimit-Reset |
UNIX timestamp indicating when the window resets. |
Standard Limits
| Endpoint group | Limit |
|---|---|
| Mandates (create, retrieve, list) | 200 requests per minute per merchant |
| Payments (create, retrieve) | 400 requests per minute per merchant |
| Payments (list) | 120 requests per minute per merchant |
| Refunds | 100 requests per minute per merchant |
| Webhook endpoint management | 30 requests per minute per merchant |
Reporting Endpoints
| Endpoint | Limit |
|---|---|
GET /payments/summary |
20 requests per minute |
GET /mandates/summary |
20 requests per minute |
GET /refunds/summary |
20 requests per minute |
Large report exports incur heavier processing and are subject to background throttling. Plan to cache results and avoid repeated calls within the same interval.
Burst Limits
Each merchant is allowed short bursts up to 2x the per-minute limit, provided the five-minute rolling window average stays within the documented thresholds. Sustained spikes beyond these limits result in progressive backoff responses.
Handling 429 Responses
- Inspect the
Retry-Afterheader (seconds) orX-RateLimit-Resetto determine when to retry. - Use exponential backoff with jitter to prevent synchronized retries.
- Spread workload across time where possible (e.g., schedule batch jobs during off-peak hours).
Webhooks vs API Calls
Webhook deliveries are not subject to these limits, but manual retries triggered via the API are. Avoid repeatedly invoking POST /webhook-events/{event_id}/retry; use Webhooks for guidance.
Monitoring
Export rate limit headers to your observability platform. Persistent exhaustion may indicate inefficient polling or missing caching layers. Review Pagination and Webhooks for strategies that reduce API volume.