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 |