Errors and retries
Catch typed Ovok errors and retry only failures that are safe to repeat.
- Stable unknown
- Release candidate since 0.4.49-rc.2
- Development since 0.4.49-dev.493+062a3db
Every failed call rejects with an OvokError. Branch on its subclass or its status and code, never on the message text.
import { OvokPermissionError, OvokRateLimitError, OvokValidationError } from '@ovok/core';
try {
await ovok.fhir.update(patient);
} catch (error) {
if (error instanceof OvokValidationError) showFieldErrors(error.fieldErrors);
else if (error instanceof OvokRateLimitError) retryLater(error.retryAfterMs);
else if (error instanceof OvokPermissionError) showNotAllowed();
else throw error;
}Which class you get
OvokValidationError: 400 or 422.fieldErrorsnames each invalid field.isRegistrationFailed(error)is true when a signup was refused because the address already has an account.OvokAuthenticationError: 401. The session has ended.OvokPermissionError: 403. The user is signed in but not allowed; the client never signs out on it.OvokNotFoundError: 404.OvokConflictError: 409, and 412 whenIf-Matchnames an older version.OvokRateLimitError: 429, withretryAfterMswhen the server sent a delay.OvokServiceError: any 5xx.OvokConnectionError: no answer at all, from a network failure or a timeout.OvokTimeoutError, a subclass, means the server did not answer withintimeoutMs.OvokConfigError: a bad client option, or an action this client cannot take, such as a machine client callingovok.auth.login.
Quote traceId when you report a problem; it matches the x-trace-id response header. The server answers with RFC 9457 problem details, so type and code stay stable across releases.
What the client retries for you
- Which requests: GET, HEAD, PUT and DELETE, plus conditional creates such as measurement saves. A plain POST is never repeated, because a lost response does not say whether the server applied it.
- Which failures: network failures and the statuses 429, 502, 503 and 504.
- How often: up to
maxNetworkRetriestimes (2 by default), waitingretryAfterMswhen the server sent it and otherwise backing off from 300 ms, never more than 5 s per wait.
Retrying yourself
- Authentication or permission: restore the session or fix the user's project access. Do not retry.
- Validation: show the field errors and let the user correct the input.
- Rate limit or service failure: wait at least
retryAfterMs, then offer a deliberate retry.
Measurement saves and the outbox already retry safely; do not wrap them in a second retry loop.
Every method takes { signal, timeoutMs } as its last argument. Aborting your own signal rejects with your abort reason, not with an OvokError.
See also
- Errors API reference: every error class and its fields.
- Access policies when a 403 is unexpected.
Last updated on