> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limiting

> Your business has one rate limit, in requests per second, shared by all its API keys. Reads served from the cache are free.

## Your business's limit

Your business has **one rate limit**, in **requests per second**, shared by every API key it has and
by every endpoint. It is set for your business from its own traffic, with room to grow.

When more requests arrive in one second than your limit allows, the ones over it are refused with
`429`; the rest of that second's requests are served, and the next second starts afresh. For
example, with a limit of 25 requests per second, 30 requests sent in the same second give 25
answers and 5 refusals.

Card authorizations are not API calls and never count against your limit.

**Need more?** Your limit can be raised. Ask your account manager, or write to
[support@fyatu.com](mailto:support@fyatu.com), and we will review it against your traffic.

## Reads from the cache are free

A successful `GET` is cached for **5 seconds** per API key. Asking for the same URL again within that
window returns the same answer **without counting against your limit**. The `X-Cache` header says
which you got:

| `X-Cache` | Meaning |
| - | - |
| `MISS` | Read fresh, and counted |
| `HIT` | Served from the cache, up to 5 seconds old, and not counted |

Writes are never cached, and neither is `GET /cards/{id}/secure-details`. To see the effect of a
write straight away, use the response of that write rather than an immediate re-read.

## Rate-limit headers

Every counted response carries the state of your limit:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Your business's requests per second |
| `X-RateLimit-Remaining` | Requests left in the current second |
| `X-RateLimit-Reset` | Unix timestamp when the next second starts |

A response served from the cache (`X-Cache: HIT`) was not counted and carries none of them.

## Over the limit

The request is refused with `429` and `Retry-After: 1`. Nothing was executed.

```json 429 Too Many Requests theme={null}
{
  "success": false,
  "status": 429,
  "message": "Rate limit exceeded: 25 requests per second",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "detail": "Rate limit exceeded: 25 requests per second"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-11-15T10:00:00Z"
  }
}
```

Send the request again after `Retry-After`. A `POST` keeps its `Idempotency-Key`, so a retry can
never act twice:

```javascript theme={null}
async function withRateLimit(send, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await send();
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get('Retry-After')) || 1;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000 * (attempt + 1)));
  }
  throw new Error('Still rate limited after retries');
}
```

## Staying well inside your limit

* **Spread bursts.** Your limit is per second: issuing 200 cards at once is better sent as a steady
  stream than as 200 simultaneous requests.
* **Use webhooks, not polling.** A card becoming ready, a funding being confirmed and a purchase being
  approved all arrive as [webhooks](https://docs.fyatu.com/v3.20/documentation/concepts/webhooks.md).
* **Watch `X-RateLimit-Remaining`.** If it keeps reaching zero, find the loop that is reading the same
  thing repeatedly, or ask for a higher limit.
* **Page through lists** with `limit` (up to 100) rather than many small requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.