Error Handling

A request the API answers with a non-2xx status throws a VimConnectError. Switch on statusCode: the API's routes do not set code today, so it is undefined.

import { VimConnectError, existingRecordIdOf } from '@vimconnect/backend-sdk';

try {
  await client.api.patient.create(input);
} catch (err) {
  const existing = existingRecordIdOf(err);
  if (existing) return client.api.patient.update({ id: existing, ...changes });
  if (err instanceof VimConnectError && err.statusCode === 403) {
    // this account did not grant your app this operation
  }
  throw err;
}

VimConnectError

Field	Type	What it holds
`statusCode`	`number`	The HTTP status.
`code`	`string \| undefined`	A machine-readable code, when the API sends one. The routes the Backend SDK calls do not, so switch on `statusCode`.
`message`	`string`	The API's message. On the token mint it is the OAuth error (`invalid_client`, `invalid_grant`, …).
`details`	`Record<string, unknown> \| undefined`	`details.operation` names the call that failed, for example `patient.create`. A `409` also carries the existing record's id, read with `existingRecordIdOf(err)`.
`response`	`Response \| undefined`	The raw `fetch` response, for headers or anything else this table does not cover.

Error statuses

Token mint

The client mints a token on the first call and again before it expires. A mint is never retried.

Status	When	How to handle
`400` `invalid_grant`	The account does not exist, or your app is not installed on it	Check `accountId`, and that the account accepted your app's invite
`400` `unauthorized_client`	The app is a point-of-care app, or has no live manifest	Use a service app's credentials; publish its manifest
`400` `Validation Error`	`clientId`, `clientSecret` or `accountId` is missing	Pass all three to `VimConnectBackendClient`
`401` `invalid_client`	The `clientId` / `clientSecret` pair is wrong	Check the credentials; rotate the secret in the Console if it leaked

Operations

Status	When	How to handle
`400`	The input is invalid: a required field is missing, a field is not declared for this operation, a filter is unknown, a protected value was sent in plaintext, or `id` is missing or not a UUID	Fix the input; the message names the field. Do not retry
`401`	The token expired	Handled for you: the client mints a new token and resends once. A second `401` reaches you; check that `accountId` is the account the token was minted for
`403`	The account did not grant your app this operation, has not accepted Vim's terms, or the record is immutable	Ask the account to grant the operation; do not retry
`404`	The record does not exist in this account, or the operation is not offered to your app	Check the id. For an operation, check your SDK version against the API reference
`409`	A `create` sent an identifier that another record already holds	Read the existing id with `existingRecordIdOf(err)` and `update` that record
`422`	A `lookup` referred to a protected value this account does not hold	Call `lookup` again with the patient's details
`500`	The API failed	Retry a read later. For a write, check whether it was applied before sending it again
`502`, `503`, `504`	The API was briefly unavailable	Reads are retried for you (see `retries` in Configuration). Writes are never re-sent; check whether one was applied before sending it again

The API does not rate-limit these routes today. A 429 from anything in between is surfaced as is and not retried.

Errors that are not a VimConnectError

Error	When	How to handle
`VimConnectWriteRevealError`	A `create` or `update` was stored, but revealing its protected fields for the reply failed. It extends `VimConnectError` and carries `written` (always `true`) and `vimEntityId`	Do not send the write again. `get` the record by `vimEntityId`
`Error: Request timed out after …ms`	No response within `timeoutMs` (default 30s). Reads are retried first	Retry a read later; check whether a write was applied before sending it again
The `fetch` error (for example `TypeError`)	The network failed before any response. Reads are retried first	Same as a timeout
Your `AbortSignal`'s reason	You aborted the call	Nothing was answered; treat as cancelled
`Error` from the constructor	`VimConnectBackendClient` was given invalid options	Fix the configuration
`Error` before a write is sent	A `create` has no value for the record's identifier field	Add the identifier; nothing was sent

EHR errors

A client.ehr call fails with a VimConnectEhrError, a VimConnectError with a code. Its codes and what to do about each are on EHR access.