Rate Limits

Each account has an overall ceiling (below). Some routes also have their own, lower per-route limits. BLOX counts these limits for each account over a rolling 60-second window. The first limit that you reach causes a 429 response. The per-route limits are all in the account ceiling, so one route cannot use all of your account ceiling.

Per-route write limits

BLOX counts each limit for each account over a rolling 60-second window.

Per-route read limits

Account ceiling

BLOX applies this limit to all endpoints together, for each account.

The sandbox ceiling is intentionally low. A load test that passes in sandbox at 100/min does not show the capacity that is available in production. Use the production ceiling to plan your load. The per-route limits above are parts of that ceiling.

Exceeded Limits

If you send more requests than a limit permits, BLOX returns 429 in the standard error format of the merchant API:

{
  "code": "RATE_LIMITED",
  "message": "Too many payout requests. Please try again later.",
  "requestId": "…"
}

Retry with exponential backoff. Rate-limit metadata headers are not always in the response.

If a write request gets a 429 response, BLOX did not process the request. Retry it with the same Idempotency-Key. This retry is safe. Refer to Idempotency.

Best Practices

1. Use exponential backoff: If you get a 429 response, wait before you retry.
2. Cache responses: Keep data in a cache where possible, to send fewer API calls.
3. Do not send repeated requests for the payout status: Register a PAYOUT webhook and use the payout.updated webhook event. Get the payout only to reconcile, or to find the status after you did not receive a webhook event. Top-ups also have webhook events (payout.prefund_completed). Thus, you do not need to send repeated requests to the balance endpoint. Get the balance when a webhook event arrives.