Rate Limits

Rate limiting is enforced on the API. Two limiters apply, both keyed by client IP address — not by credential or organization.

Note

Treat the budgets below as the guaranteed floor, not a precise ceiling. Counters are held per API instance rather than in a shared store, so the point at which you actually see a 429 depends on how your requests land across instances, and counters reset when an instance restarts. Size your client against the documented budget; do not calibrate it against the larger number you may observe in practice.

Global limit

Every endpoint is covered by a global limiter:

Budget	300 requests per 60 seconds per IP
Applies to	All endpoints, including /v1/ussd/*, /v1/customers, /v1/payment/* and /v1/webhooks/callback
Exempt	/healthz and /metrics

Exceeding it returns 429 Too Many Requests:

{
  "error": "Too Many Requests",
  "message": "Too many requests. Please slow down and try again shortly."
}

Token-endpoint limit

POST /v1/oauth/token carries a second, much stricter limiter on top of the global one, to blunt brute-forcing of client secrets:

Budget	10 requests per 15 minutes per IP
Applies to	POST /v1/oauth/token

Exceeding it returns 429 Too Many Requests:

{
  "error": "Too Many Requests",
  "message": "Too many authentication attempts. Please try again in a few minutes."
}

Caution

Ten token requests per fifteen minutes is a tight budget. Cache your access token and reuse it until it expires rather than exchanging credentials on every call — a token is valid for one hour by default. A client that re-authenticates per request will be throttled quickly.

Response headers

Both limiters emit the RFC draft-6 rate-limit headers, as four separate fields:

Header	Meaning	Example
RateLimit-Limit	Requests allowed in the current window	300
RateLimit-Remaining	Requests left in the current window	299
RateLimit-Reset	Seconds until the window resets	60
RateLimit-Policy	The policy being applied, as limit;w=window-seconds	300;w=60
Retry-After	Sent on a 429 — seconds to wait before retrying	47

Note

There is no combined RateLimit header — the budget is spread across RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. The legacy X-RateLimit-* headers are not sent either.

Exempt endpoints carry no rate-limit headers at all, so do not treat their absence as a budget of zero.

Handling a 429

Back off rather than retrying immediately:

1. Read Retry-After and wait at least that long.
2. Retry with exponential backoff and jitter.
3. Because the limit is per IP, several processes behind one egress address share a single budget. Account for that when sizing concurrency.

A retried mutating request must reuse the same X-Idempotency-Key so the operation still happens at most once.