Errors and retries
The SDK maps several backend responses into typed errors. Use the exported type guards and structured fields so UI behavior does not depend on wording that can change.
| Error helper | Use |
|---|---|
readOvokError(error) | Read Ovok status, stable code, message, and field errors from an API error. |
isRateLimitError(error) | Detect throttling and read retryAfterMs. |
isSignInRequiredError(error) | Detect an operation the SDK rejected before making a request because the user is signed out. |
isSignalsError(error) | Read a structured error from a Signals integration call. |
isRegistrationFailed(error) | Show the neutral registration failure state defined by the backend contract. |
Retry only transient outcomes
Before retrying, classify the failure:
- Authentication or authorization: restore a valid session or fix project membership/AccessPolicy. Do not retry automatically.
- Validation: show the relevant field errors and let the user correct the input.
- Rate limit: wait for
retryAfterMs, then offer a deliberate retry. - Temporary network or service failure: use a bounded retry with backoff where the workflow is safe to repeat.
Measurement writes use conditional creates to make retries idempotent. The offline queue already tracks retries. Avoid layering a second unbounded retry loop over either mechanism.
For FHIR status codes and operation behavior, consult the relevant page in the Ovok FHIR API reference and the related backend guide. For authorization failures, start with Access policies.