Getting Started

Rate limiting

How rate limits work and which response headers to use for backoff and retries.

For our initial API design, rate limits protect the API from abuse and help clients throttle proactively. The figures below are the documented design baseline supplied for this page.

Tiers

Tier	Limit	Endpoints
Standard	100 / minute	Token, airtime, bills, messages, balance and status.
Payment	50 / minute	Payment and payout operations.

Behaviour

Sliding 60-second window per rate-limit key.
Limits are applied per tier.
When a limit is exceeded, the API returns 429 Too Many Requests.
Clients should use response headers to throttle before reaching the limit.

Response headers

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window.
X-RateLimit-Remaining	Requests remaining in the current window.
X-RateLimit-Reset	Unix timestamp in seconds when the window resets.
Retry-After	On 429 responses, recommended wait time in seconds.

Example: success response

HTTP 200

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1234567890
Content-Type: application/json

Example: payment tier

HTTP 200

HTTP/1.1 200 OK
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1234567890

Example: rate limit exceeded

HTTP 429

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1234567890
Content-Type: application/json

{{"error":"Too many requests."}}

Best practices

Monitor X-RateLimit-Remaining.
Use X-RateLimit-Reset to schedule the next attempt.
On 429, wait at least Retry-After seconds.
Use exponential backoff for repeated 429 responses.