# Errors and retries

Canonical page: https://docs.ovok.com/web-sdk/core/errors-and-retries

Every failed call rejects with an `OvokError`. Branch on its subclass or its `status` and `code`, never on the message text.

```ts
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 [#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 [#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 [#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](./namespaces/outbox.mdx) 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 [#see-also]

- [Errors API reference](./reference/core/errors.mdx): every error class and its fields.
- [Access policies](https://docs.ovok.com/access-policies) when a 403 is unexpected.
