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. fieldErrors names 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 when If-Match names an older version.
  • OvokRateLimitError: 429, with retryAfterMs when 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 within timeoutMs.
  • OvokConfigError: a bad client option, or an action this client cannot take, such as a machine client calling ovok.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 maxNetworkRetries times (2 by default), waiting retryAfterMs when the server sent it and otherwise backing off from 300 ms, never more than 5 s per wait.

Retrying yourself

  1. Authentication or permission: restore the session or fix the user's project access. Do not retry.
  2. Validation: show the field errors and let the user correct the input.
  3. 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

Last updated on

On this page