> This page is for version 2024-10-01 (default).
> For other versions, use one of these documentation indexes:
> - 2024-10-01 (default): https://docs.getkard.com/2024-10-01/llms.txt
> - Legacy: https://docs.getkard.com/legacy/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getkard.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server.

# 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.

> **Note**
>
> Limits apply per issuer to all API endpoints called with your issuer access token.

### Example

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

| Time               | Requests sent | Allowed rate | Result                                      |
| ------------------ | ------------- | ------------ | ------------------------------------------- |
| Before the jump    | 400 RPS       | \~420 RPS    | All requests succeed                        |
| 1 second after     | 1,200 RPS     | \~420 RPS    | Requests above the allowed rate get a `429` |
| 10 seconds after   | 1,200 RPS     | \~690 RPS    | Fewer requests get a `429`                  |
| \~22 seconds after | 1,200 RPS     | \~1,200 RPS  | All requests succeed again                  |

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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429)
response with a `Retry-After` header (in seconds) and a body in the standard error format:

```http
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 `429`s.
* 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.