Skip to main content

Rate Limiting

The Pagamio VAS API enforces rate limits on a small set of high-risk endpoints to protect the platform from abuse and to ensure fair usage.

Rate Limit Policies​

EndpointLimitScopePurpose
POST /auth/token5 requests / minuteIP addressPrevents brute-force credential attacks.
POST /auth/token/refresh10 requests / minuteIP addressLimits abuse of the token refresh endpoint.
POST /purchase10 requests / minuteUser tokenProtects the transaction pipeline from runaway loops.

All other endpoints currently have no per-endpoint rate limit. This may change in future releases without breaking the contract — always handle 429 responses defensively.

Limits are configurable on the platform side and the values above are the defaults. If your account has a different limit, your account manager will inform you.

What A Rate-Limited Response Looks Like​

When a limit is exceeded, the API returns HTTP 429 Too Many Requests with this body:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded for /purchase"
}

The current implementation does not return Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, or X-RateLimit-Reset headers. Do not write client code that depends on these headers.

  1. On 429, back off and retry. A safe starting policy is exponential backoff with jitter:
    • Wait 1s, then 2s, then 4s, then 8s (capped at 60s).
    • Add up to ±25% random jitter to avoid thundering herd retries.
  2. Never retry a 429 immediately. The bucket refills on a per-minute interval.
  3. Spread bulk operations over time. If you have many merchants transacting through one token, consider one token per merchant where possible.

Last updated: April 2026