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

# Rate Limits

> How to handle API request limits and retry behavior.

Stabyl applies request limits to keep API performance consistent and protect
trading and wallet workflows from accidental request bursts. Limits can vary by
route and account. Do not hardcode an assumed request allowance unless Stabyl
has provided one for your production onboarding.

## Required Headers

Send `X-Api-Key` on authenticated endpoints so limits are evaluated for the correct account. Send `Idempotency-Key` on order writes so retries are safe.

## Handling Limits

When a request is rate limited, the API returns `429` with error code
`RATE_LIMITED`. A `Retry-After` header is not guaranteed, so clients must have a
bounded backoff policy. Use exponential backoff with full jitter, starting near
one second and capped near 30 seconds.

| Pattern           | Recommendation                                                                                           |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| Stable reads      | Cache route lists, currencies, and market metadata                                                       |
| Live market data  | Prefer WebSocket topics when continuous updates are required                                             |
| Order lifecycle   | Prefer exchange webhooks or private WebSocket topics                                                     |
| Wallet lifecycle  | Prefer deposit and withdrawal webhooks                                                                   |
| Order writes      | Retry with the same `Idempotency-Key` after a transient failure                                          |
| Withdrawal writes | Keep the same body and business idempotency key, but sign each HTTP retry with a new timestamp and nonce |
| Batch jobs        | Add jitter so scheduled jobs do not all run at the same second                                           |

## Suggested Client Behavior

| Response                              | Client behavior                                                   |
| ------------------------------------- | ----------------------------------------------------------------- |
| `429`                                 | Use bounded exponential backoff with full jitter                  |
| `5xx` on an order write               | Retry with the same `Idempotency-Key`                             |
| `429` or `5xx` on a signed withdrawal | Follow the signed retry rules in [Withdrawals](/docs/withdrawals) |
| repeated `429`                        | Slow the whole account-level queue, not only one request          |

Cap attempts and surface persistent rate limiting to operators. Do not retry
validation, authentication, or permission failures as if they were rate limits.

## Event and reconciliation guidance

| Resource               | Typical pattern                                                         |
| ---------------------- | ----------------------------------------------------------------------- |
| Markets and currencies | Refresh at startup and periodically                                     |
| Ticker and order book  | Read before an action; use WebSocket for continuous updates             |
| Orders and fills       | Consume webhooks or WebSocket; use REST for recovery and reconciliation |
| Wallet transactions    | Consume webhooks; run cursor-based REST reconciliation periodically     |
| Deposit address        | Read on demand, then cache the returned address                         |