Rate limits & circuit breakers

Rate limits protect both our downstream carrier partners and your wallet balance using an intelligent failure circuit-breaker mechanism scoped per product group, API key, and IP address.

How the failure circuit breaker works

Unlike blunt rate limiters that throttle healthy production throughput, the Partner API rate limiter functions as a failure circuit breaker:

• Healthy requests pass freely: When your requests return success: true, the failure attempt counter is instantly reset to 0.
• Consecutive failures trip the breaker: If your system emits 30 failed requests (e.g. 400 Bad Request, missing parameters, invalid accounts) on a specific route within a 60-second sliding window, the circuit breaker trips.
• Lockout period: Once tripped, that route is locked out for 60 seconds for your key and IP, returning 429 Too Many Requests.
• Auth bypass: Unauthenticated requests (401) and unprocessable entities (422) do not increment the failure circuit breaker.

Protected route groups

Circuit breaker response (429)

When locked out, the API returns a 429 Too Many Requests error with the remaining seconds in details.retryAfter:

{
  "success": false,
  "message": "Too many requests. Try again in 42 seconds",
  "error": "RATE_LIMIT_EXCEEDED",
  "details": {
    "retryAfter": 42
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/airtime/purchase"
}

Integration best practices

• Validate client inputs locally: Validate phone number formats, amounts, and required slugs on your backend before calling the API to avoid accumulating failures.
• Cache catalog responses: Cache network slugs, DISCO providers, and data bundles in Redis or memory for 1 to 6 hours. They change infrequently.
• Respect retryAfter: If your system receives a 429, parse details.retryAfter and suspend retries for that duration rather than creating a retry storm.