Rate Limits

Ramp limiting

The Kard API limits how fast an issuer’s traffic can grow, not how much traffic an issuer can send. Steady traffic and gradual growth are not limited. A large, sudden jump in requests per second (RPS) is slowed down with 429 responses, so our services have time to scale up and stay fast for everyone.

Each issuer has an allowed rate that follows its real traffic:

• Every issuer can send at least 100 RPS. Below that, you will not be limited.
• The allowed rate grows about 5% every second (at least 10 RPS per second) while your traffic is rising. That means it can double in about 15 seconds.
• Short bursts are absorbed. If your traffic has been steady for a while, up to one second’s worth of requests (and at least 400), counting your regular traffic, can arrive at once. Repeated bursts less than about 30 seconds apart may be limited.
• When your traffic drops, the allowed rate falls by 10 RPS each second. Returning to your previous level within a few seconds is not limited. After a longer pause, the allowed rate ramps up again as described above.

Example

An issuer steadily sending 400 RPS suddenly jumps to 1,200 RPS.

If the same issuer had grown from 400 RPS to 1,200 RPS over a few minutes, no requests would have been limited.

Handling a 429 response

A limited request gets an HTTP 429 Too Many Requests response with a Retry-After header (in seconds) and a body in the standard error format:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{
  "errors": [
    {
      "status": "429",
      "title": "Too Many Requests",
      "detail": "Too many requests for this issuer; retry after the Retry-After header"
    }
  ]
}

A limited request was not processed, so it is safe to retry. We recommend that you:

• Wait at least the Retry-After value before retrying, and use exponential backoff with jitter on repeated 429s.
• Grow traffic gradually where you can, for example by spreading out batch jobs instead of starting them all at once.
• Contact your Kard representative ahead of planned launches, campaigns, or anything else that will sharply increase your traffic.