Error Codes

Reference for all Circadify SDK and API error codes.

When something goes wrong, the SDK throws a CircadifyError instance with a machine-readable code, a human-readable message, and a flag indicating whether your application may safely retry the operation.

Error Format

All SDK errors are instances of the CircadifyError class, which extends the native Error. You can import both the class and the error code enum for type-safe handling.

import { CircadifyError, CircadifyErrorCode } from '@circadify/web-sdk';

class CircadifyError extends Error {
  code: CircadifyErrorCode;             // Machine-readable error code
  message: string;                      // Human-readable description
  isRetryable: boolean;                 // Whether YOUR APP may retry the operation
  details?: Record<string, unknown>;    // Extra context (e.g. retryAfterSeconds on RATE_LIMITED)
  cause?: Error;                        // Underlying error, when available
}

Use instanceof CircadifyError to distinguish SDK errors from other exceptions:

try {
  const video = document.querySelector('video')!;
  const result = await sdk.measureVitals({ videoElement: video });
} catch (error) {
  if (error instanceof CircadifyError) {
    console.error(`[${error.code}] ${error.message} (retryable: ${error.isRetryable})`);
  }
}

How to Read "Retryable"

The Retryable column below mirrors the SDK's own error.isRetryable flag exactly. Three rules:

1. The SDK never retries failed operations internally. Result polling (every 2 seconds, up to 120 seconds) is part of the normal flow, not a retry — every thrown error reaches your code, and any retry is your application's decision.
2. Retryable: Yes (isRetryable === true) means your app may automatically retry the whole measureVitals() call with exponential backoff. Only four codes qualify: NETWORK_ERROR, UPLOAD_FAILED, TIMEOUT, and RATE_LIMITED.
3. Retryable: No means do not build an automated retry loop on this code. Many "No" codes are still user-recoverable — e.g. FACE_DETECTION_TIMEOUT can succeed on a fresh scan after the user fixes lighting or framing. Offer a manual "Scan again" button; never loop programmatically. Others (QUOTA_EXCEEDED, INVALID_API_KEY, CANCELLED) will keep failing until an account, configuration, or user decision changes.

SDK Error Codes

These errors originate from the client-side SDK during the measureVitals() lifecycle.

Initialization Errors

Camera Errors

Capture Errors

Network and Processing Errors

API Error Codes

These errors originate from the Circadify API and are surfaced by the SDK as CircadifyError instances. For the full server-side error reference, see REST API Errors.

On Web SDK 4.1.0+, authentication, session, and quota problems that occur during the upload also surface as their precise codes (INVALID_API_KEY, SESSION_EXPIRED, QUOTA_EXCEEDED, …) rather than a generic UPLOAD_FAILED — so UPLOAD_FAILED reliably indicates a genuine transfer or server failure.

Fallback Vitals and Errors

By default, every failure above is thrown to your code — the SDK never substitutes a result for an error. There is one opt-in exception: if you set allowFallbackVitals: true in the SDK configuration, the three transient infrastructure failures (UPLOAD_FAILED, NETWORK_ERROR, TIMEOUT) — only when they occur during the upload/processing phase — resolve with a synthetic placeholder result marked isFallback: true and confidence: 0 instead of throwing. Fallback values are not measurements. The same codes thrown in other phases still throw: the capture watchdog's TIMEOUT (too few frames within 60 seconds) and a NETWORK_ERROR from session start always throw regardless of this setting, as do all other error codes. Leave the option off unless you have read the fallback documentation and your UI explicitly handles isFallback.

Handling Errors

Basic pattern

Wrap measureVitals() in a try/catch and branch on the error code:

import { CircadifySDK, CircadifyError, CircadifyErrorCode } from '@circadify/web-sdk';
 
try {
  const result = await sdk.measureVitals({
    videoElement: document.getElementById('preview') as HTMLVideoElement,
  });
} catch (error) {
  if (!(error instanceof CircadifyError)) throw error;
 
  switch (error.code) {
    case CircadifyErrorCode.CAMERA_PERMISSION_DENIED:
      showMessage('Please allow camera access to measure your vitals.');
      break;
    case CircadifyErrorCode.QUOTA_EXCEEDED:
      showMessage('Monthly scan quota reached. Scans resume next cycle.');
      break;
    case CircadifyErrorCode.CANCELLED:
      // User cancelled — no action needed
      break;
    default:
      if (error.isRetryable) {
        showRetryButton(error.message);
      } else {
        showError(error.message);
      }
  }
}

Retry with backoff

For retryable errors (isRetryable === true — only NETWORK_ERROR, UPLOAD_FAILED, TIMEOUT, RATE_LIMITED), implement exponential backoff:

async function measureWithRetry(sdk: CircadifySDK, options: MeasurementOptions, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await sdk.measureVitals(options);
    } catch (error) {
      if (!(error instanceof CircadifyError) || !error.isRetryable || attempt === maxRetries) {
        throw error;
      }
      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Because this loop gates on isRetryable, it will correctly not retry condition errors (FACE_DETECTION_TIMEOUT, CAMERA_IN_USE, WASM_LOAD_FAILED, …) — those need the user or the environment to change first. Handle them with a manual "Scan again" affordance instead.

Camera permission recovery

When the user denies camera access, guide them to their browser settings:

try {
  const video = document.querySelector('video')!;
  const result = await sdk.measureVitals({ videoElement: video });
} catch (error) {
  if (error instanceof CircadifyError && error.code === CircadifyErrorCode.CAMERA_PERMISSION_DENIED) {
    showInstructions(
      'Camera access is required. Open your browser settings and allow camera access for this site, then refresh the page.'
    );
  }
}

Next Steps

• Events — Monitor errors via event listeners
• Configuration — Including the allowFallbackVitals safety documentation
• REST API Errors — Server-side error reference