Error Handling

When a request fails, the API returns an appropriate HTTP status code and an error object in the response body.

Error response

Every error response has the same shape:

{
  "error": {
    "code": 404,
    "type": "NotFoundError",
    "title": "Vitals Scan not found"
  }
}

Field	Type	Description
code	number	The HTTP status code, repeated in the body for convenience.
type	string	A stable, machine-readable identifier for the error. Branch on this rather than parsing the title.
title	string	A human-readable description of what went wrong. The wording may change, so do not depend on it.

Each endpoint’s reference page lists the specific type values it can return for each status code.

Every response also includes an x-request-id header. Include it when contacting support about a failed request. See Request IDs.

HTTP status codes

Status	Meaning	Common causes
400	Bad Request	Invalid input, expired link, disabled link, max scans reached, insufficient credits
401	Unauthorized	Missing or invalid API key
403	Forbidden	Authenticated, but not permitted to access this resource
404	Not Found	Resource does not exist or does not belong to your business
409	Conflict	Patient with this email already exists (when using mode: "create")

Error types

Branch on error.type to handle specific failures programmatically. Common values include:

type	Status	Meaning
BadRequestError	400	The request was malformed or failed validation.
InsufficientCreditsError	400	Not enough credits to create or start the scan.
VitalsLinkExpiredError	400	The vitals link has expired.
VitalsLinkScanLimitError	400	The vitals link has reached its maximum number of scans.
InvalidRedirectUrlError	400	The supplied redirect URL is not a permitted Upvio domain.
UnauthenticatedError	401	The API key is missing or invalid.
UnauthorizedError	403	Authenticated, but not permitted to access this resource.
NotFoundError	404	The requested resource does not exist.
PatientEmailExistsError	409	A patient with this email already exists.

The full set of type values an endpoint can return is documented on that endpoint’s reference page.

Handling errors with the SDK

The SDK returns a response object with an optional error field instead of throwing exceptions. Check response.error to detect failures, and branch on response.error.type.

SDK

import { UpvioApiClient } from '@upvio/sdk-node'

const client = new UpvioApiClient({
  apiKey: process.env.UPVIO_API_KEY,
  businessId: process.env.UPVIO_BUSINESS_ID,
})

const response =
  await client.v1.vitals.scans.retrieve('invalid-id')

if (response.error) {
  console.error(response.error.code)  // 404
  console.error(response.error.type)  // "NotFoundError"
  console.error(response.error.title) // "Vitals Scan not found"

  if (response.error.type === 'InsufficientCreditsError') {
    // Handle the out-of-credits case specifically.
  }
}

fetch

const response = await fetch(
  `https://api.upvio.com/v1/businesses/${businessId}/vitals/scans/invalid-id`,
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
)

if (!response.ok) {
  const body = await response.json()
  console.error(response.status)   // 404
  console.error(body.error?.type)  // "NotFoundError"
  console.error(body.error?.title) // "Vitals Scan not found"
}

Common error scenarios

Scenario	Status	type
API key missing or invalid	401	UnauthenticatedError
Scan link is expired	400	VitalsLinkExpiredError
Scan link is disabled or archived	400	BadRequestError
Scan link reached its maximum scans	400	VitalsLinkScanLimitError
Insufficient scan credits	400	InsufficientCreditsError
Duplicate patient email with mode: "create"	409	PatientEmailExistsError
Resource not found	404	NotFoundError