Handle API rate limits effectively
- Treat REST request limits and realtime control-plane limits as different problems.
- Build retry behavior around classification rather than around one generic backoff rule.
- Track request and reconnect pressure before it becomes visible as hard failures.
- Preserve local state and idempotency context while throttling.
- Resume at a controlled pace after throttling instead of replaying a burst.
Separate the rate-limit surfaces
| Surface | What to plan for |
|---|---|
| REST request submission | documented DDX-balance tiers, burst behavior, and 429 RateLimit handling |
| Realtime control plane | connection, flooding, and subscribe or unsubscribe pressure without assuming one published numeric table |
| Webserver or leader transitions | delayed responses, 421, or 503 that can look like rate problems but require different recovery posture |
Build the retry policy by class
- On
429 RateLimit, use bounded exponential backoff with jitter. - On replay-window or signing failures, rebuild the request instead of retrying unchanged.
- On
SafetyFailure, fix the request or account state first. - On WebSocket control-plane errors, slow the subscribe or unsubscribe pattern before reopening more connections.
Reduce burst pressure before the server has to
- batch or schedule non-urgent writes
- avoid reconnect storms across multiple workers
- avoid repeated subscribe and unsubscribe churn for the same symbols
- prefer one durable connection with measured resubscribe logic over many short-lived sockets
Keep throttling from corrupting state
- Record the request identifier, nonce, timestamp, and intended action before submission.
- If throttling delays the write path, do not assume the order never reached the system.
- Reconcile the eventual outcome from REST and realtime before replaying the same intent.
- Treat delayed responses during bursts as pressure signals even before a visible
429.