Error Handling

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

Error response

{
  "error": {
    "code": "not_found",
    "title": "Vitals Link not found"
  }
}

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
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")

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.

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)  // "not_found"
  console.error(response.error.title) // "Vitals Scan not found"
}

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?.title)    // "Vitals Scan not found"
}

Common error scenarios

Scenario	Status	Title
API key missing or invalid	401	Unauthorized
Scan link is expired	400	Link has expired
Scan link is disabled	400	Link is disabled
Scan link reached max scans	400	Maximum scans reached
Insufficient scan credits	400	Insufficient credits
Duplicate patient email with mode: "create"	409	A patient with this email already exists
Resource not found	404	{Resource} not found