Rate Limits

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. Per-key limits return the JSON envelope with error code RATE_LIMITED and no Retry-After header. A separate edge limiter, applied per source IP, returns 429 with a plain-text body and a Retry-After header. Treat any 429 the same way regardless of body shape: clients must have a bounded backoff policy. Use exponential backoff with full jitter, starting near one second and capped near 30 seconds. Signed withdrawal quote and submit calls are limited separately from, and much more tightly than, the rest of the key’s traffic. Quote as part of a user action, not in a polling loop, and never retry a submit in a tight loop.

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

Get Started

Wallets

Exchange

Webhooks

WebSocket

Required Headers

Handling Limits

Suggested Client Behavior

Event and reconciliation guidance

​Required Headers

​Handling Limits

​Suggested Client Behavior

​Event and reconciliation guidance

Required Headers

Handling Limits

Suggested Client Behavior

Event and reconciliation guidance