Rate limits

Rate limits exist so one tenant’s traffic spike can’t take down another’s. Limits are per-tenant, not per-key.

Reading the headers

Every API response includes:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 327
X-RateLimit-Reset: 1716115200
X-RateLimit-Resource: passes_write

• X-RateLimit-Limit — requests allowed in the current window.
• X-RateLimit-Remaining — how many are left.
• X-RateLimit-Reset — Unix timestamp when the window resets.
• X-RateLimit-Resource — which bucket this limit applies to.

When you hit a limit, the response is 429 rate_limited:

HTTP/1.1 429 Too Many Requests
Retry-After: 4
{
  "error": {
    "type": "rate_limited",
    "code": "tenant_limit",
    "message": "Tenant rate limit exceeded for `passes_write`. Retry in 4 seconds.",
    "retry_after_ms": 4000
  }
}

Honor Retry-After. The TS SDK does this automatically.

Default limits

These are the production defaults. Sandbox uses the same envelope but can be temporarily lifted for load tests — see below.

Bucket	Default limit	Window
read (any GET)	1000 req	1 minute, per tenant
passes_write	500 req	1 minute
cards_write	200 req	1 minute
settlements_write	100 req	1 minute
templates_write	60 req	1 minute
webhooks_outbound	100 events/sec	n/a (delivered fairly)
Concurrent connections	64	n/a

Bursts up to 2× the per-minute limit are allowed using a token-bucket algorithm; sustained traffic averages out to the stated limit.

Bulk endpoints

If you find yourself bumping into the per-endpoint limit, look at the bulk variant first:

Single	Bulk
POST /v1/passes	POST /v1/passes/batch (up to 100 per call)
PATCH /v1/passes/{id}	POST /v1/passes/batch_update (up to 100 per call)
POST /v1/passes/{id}/revoke	POST /v1/passes/batch_revoke (up to 1000 per call)

Each bulk endpoint counts as one request against the bucket.

Requesting a higher limit

If your steady-state traffic exceeds the defaults, email [email protected] with:

1. The bucket you need lifted.
2. The peak rate you’ll send.
3. The duration (steady state, or a one-time burst window).

We approve most reasonable requests within one business day. For sandbox load tests, we lift sandbox-only limits same-day.

Caution

Don’t game the rate limiter with multiple API keys — limits are per-tenant. Multiple keys share the same bucket.

Webhook retries and your endpoint

If your webhook endpoint can’t keep up, QairoPay won’t slow down delivery — it’ll mark failed deliveries for retry. See Retries and delivery for how that works and how to scale your endpoint.