Errors, limits, and retries
Use stable error codes, bounded request options, opaque pagination, and deliberate retry/reconciliation.
Stable error boundary
Public failures use a stable code and HTTP status with a request ID and optional retry guidance. SDKs narrow these into typed errors. Raw server messages are not a client contract and should not be displayed or logged.
Choose the recovery action
| Class | Typical client action |
|---|---|
| Authentication expired | Allow the SDK token provider one forced refresh; otherwise end the session. |
| Resource not found | Remove stale local presentation or re-check the selected scope; do not probe for foreign existence. |
| Version conflict | Read current state, merge or reapply user intent, and submit with the new expected version. |
| Rate limited / unavailable | Respect Retry-After, use backoff, and cancel when the owning workflow is obsolete. |
| Ambiguous mutation transport failure | Read the fixed-identity resource and reconcile before replay. |
| Realtime gap / stale | Pause local continuity, refresh authoritative REST state, then resume from an acknowledged baseline. |
Important bounds
- Use the limit documented on each operation; unbounded list queries are not supported.
- Pass opaque cursors unchanged and keep them inside the scope that issued them.
- Bound request timeouts and cancel obsolete UI or server work.
- WebSocket frames, subscriptions, commands, presence watches, typing contexts, and recovery history are bounded.
- Custom JSON, arrays, text, files, filters, and sorts have operation-specific allowlists and size limits.