# Errors and limits

Use idempotency keys, bounded retries, and trade polling to keep integrations predictable.

## Idempotency

Wallet and financial mutations require `Idempotency-Key`. Reusing a key with the same request recovers the original operation. Store the exact body and key before sending the request. For a batch, preserve the entry order as well.

Use a new key for a new operation only after resolving any earlier submission. A timeout, disconnect, expired quote, or later rate-limit response does not prove that the original trade failed. Once a trade ID is known, poll its status instead of starting another trade.

Some settings changes, such as tracker settings and referral-code selection, do not use an idempotency header. The portfolio batch POST is a read. Check the endpoint's request schema instead of treating every POST as a financial mutation.

## Rate limits

| Scope | Limit |
| --- | --- |
| Account API traffic | 100 requests per second with a burst of 200 |
| Single trade submission, shared by quote submission and one-request execution | 5 requests per second with a burst of 5 |
| Trade batch submission | 1 request per second |
| Coordinated clip submission | 1 request per second |
| Buy-route previews | 10 requests per second with a burst of 10 |
| Wallet export, shared by single and bulk export | 5 requests per minute with a burst of 5 |
| Wallet import | 5 requests per minute with a burst of 5 |
| Withdrawals | 10 requests per minute with a burst of 10 |
| Account-to-account transfers | 10 requests per minute with a burst of 10 |

Limits are account-scoped. Endpoint limits apply in addition to the account limit; market-data and automation endpoints have their own limits too. Provider capacity and the website proxy may impose further limits. Use bounded backoff with jitter and avoid retrying every request at once.

## Retry decisions

| Status | Action |
| --- | --- |
| `400` | Correct the request before retrying |
| `401` | Replace or reauthorize the API key |
| `403` | Check credential scope, browser-session requirements, and CSRF headers |
| `404` | Confirm the wallet, quote, trade, or ticket identifier |
| `409` | Resolve the conflicting resource state |
| `429` | Retry with bounded exponential backoff |
| `503` | Retry temporary failures with bounded exponential backoff |

Keep the same idempotency key when retrying a mutation after a timeout, `429`, or temporary `503`.

HTTP `202` means a trade was accepted for asynchronous execution. It does not mean the trade confirmed. Follow `queued`, `submitted`, and `awaiting_ticket_refund` until `confirmed` or `failed`. A balance or portfolio refresh can fail after a successful trade; retry the read without submitting another trade.