+status: 401 } class AuthorizationError { +status: 403 } class NotFoundError { +status: 404 } class RateLimitError { +retryAfter?: number
+status: 429 } class ServiceUnavailableError { +status: 503 } class NetworkError { +status: undefined } class TimeoutError { +status: undefined } class AdverseMediaFailedError { +jobId?: string } class PollTimeoutError { +timeoutMs?: number
+jobId?: string } Error <|-- DeepIDVError DeepIDVError <|-- ValidationError DeepIDVError <|-- InsufficientFundsError DeepIDVError <|-- AuthenticationError DeepIDVError <|-- AuthorizationError DeepIDVError <|-- NotFoundError DeepIDVError <|-- RateLimitError DeepIDVError <|-- ServiceUnavailableError DeepIDVError <|-- NetworkError DeepIDVError <|-- TimeoutError DeepIDVError <|-- AdverseMediaFailedError DeepIDVError <|-- PollTimeoutError ``` All error classes are exported from `@deepidv/server`: ```typescript theme={null} import { DeepIDVError, ValidationError, AuthenticationError, AuthorizationError, InsufficientFundsError, NotFoundError, RateLimitError, ServiceUnavailableError, NetworkError, TimeoutError, AdverseMediaFailedError, PollTimeoutError, } from '@deepidv/server'; ``` ## Error catalog ### `DeepIDVError` (base class) The base class for all SDK errors. Carries HTTP context when available. | Field | Type | Description | | ---------- | -------------------------- | ------------------------------------------------------------ | | `message` | `string` | Human-readable error description | | `status` | `number \| undefined` | HTTP status code (undefined for network/timeout errors) | | `code` | `string \| undefined` | Machine-readable error code from the API | | `response` | `RawResponse \| undefined` | Raw HTTP response with `status`, `headers`, and `body` | | `cause` | `unknown` | Original error that triggered this one (`Error.cause` chain) | Every subclass implements `toJSON()` for structured logging (see below). ### `ValidationError` — HTTP 400 Thrown on HTTP `400`, **or before any network call** when input fails Zod schema validation. The message names the offending field. ```typescript theme={null} try { // Missing required 'image' field await client.document.scan({} as any); } catch (err) { if (err instanceof ValidationError) { console.error(err.message); // "Required at 'image'" } } ``` ### `AuthenticationError` — HTTP 401 Your API key is invalid, expired, or missing. Carries `redactedKey` (last 4 characters only) — safe to log. ```typescript theme={null} catch (err) { if (err instanceof AuthenticationError) { console.error(`Invalid API key: ${err.redactedKey}`); // "****abcd" } } ``` ### `InsufficientFundsError` — HTTP 402 The funds / subscription gate failed — your account doesn't have enough balance for the requested operation. ### `AuthorizationError` — HTTP 403 The API key is valid but lacks permission for the requested resource. ### `NotFoundError` — HTTP 404 The requested resource doesn't exist — e.g. an unknown session ID, or an async job that has been pruned by TTL. ### `RateLimitError` — HTTP 429 Thrown **after all retries are exhausted**. The SDK already retried with exponential backoff, so you've hit a sustained rate limit. `retryAfter` (seconds, from the `Retry-After` header) tells you how long to wait. ```typescript theme={null} catch (err) { if (err instanceof RateLimitError) { console.error(`Rate limited. Retry after ${err.retryAfter}s`); } } ``` ### `ServiceUnavailableError` — HTTP 503 A transient upstream timeout. Some screening methods (`pepSanctions`, `titleCheck`) surface this immediately without retrying because the server bounds an un-cancellable upstream — back off and try again later. ### `NetworkError` A network-level failure: DNS resolution failure, connection refused, socket hangup. `status` is `undefined`. ### `TimeoutError` A single attempt exceeded the configured `timeout` (API requests) or `uploadTimeout` (uploads). Consider increasing the relevant timeout in [configuration](/integrate/sdks/typescript/server/configuration), or retrying. ### `AdverseMediaFailedError` An [adverse-media](/integrate/sdks/typescript/server/reference/screening#adversemediainput) async job terminated in the `failed` state. Carries the `jobId` that failed. ### `PollTimeoutError` `AdverseMediaHandle.wait()` exceeded its `timeoutMs` budget before the job completed. This does **not** mean the job died — it may still complete server-side. Carries `timeoutMs` and `jobId`; resume by polling [`client.asyncJobs.get(jobId)`](/integrate/sdks/typescript/server/reference/async-jobs-events). ## Retry semantics The SDK retries only **transient** failures — HTTP `429` and `5xx` — up to `maxRetries` times (default `3`) with exponential backoff and jitter. It **never** retries `4xx` client errors, since those are caller bugs a retry won't fix. By the time a `RateLimitError` reaches your `catch` block, the retries are already spent. See [Configuration → retry & timeout behavior](/integrate/sdks/typescript/server/configuration#retry--timeout-behavior) for tuning, and note that `screening.pepSanctions` / `screening.titleCheck` deliberately opt out of retries. ## Error decision tree ```mermaid theme={null} flowchart TD A[Caught an error] --> B{instanceof?} B -->|ValidationError| E["Check your input
err.message names the field"] B -->|AuthenticationError| C["Check your API key
err.redactedKey shows last 4"] B -->|AuthorizationError| K["Key lacks permission
for this resource"] B -->|InsufficientFundsError| L["Top up account balance
or subscription"] B -->|NotFoundError| M["Resource does not exist
check the ID"] B -->|RateLimitError| D["Over quota — SDK already retried
err.retryAfter has wait time"] B -->|ServiceUnavailableError| N["Transient upstream timeout
back off and retry"] B -->|TimeoutError| F["Too slow — increase timeout
or uploadTimeout"] B -->|NetworkError| G["Connection failed
check internet, DNS, baseUrl"] B -->|DeepIDVError| H["Other API error
check err.status and err.response.body"] ``` ## Structured logging with `toJSON()` Every `DeepIDVError` implements `toJSON()`, so `JSON.stringify()` produces a clean, log-safe object. The full API key is never serialized: ```typescript theme={null} try { await client.sessions.retrieve('invalid-id'); } catch (err) { if (err instanceof DeepIDVError) { console.log(JSON.stringify(err)); // { // "type": "DeepIDVError", // "message": "Not Found", // "status": 404, // "code": "not_found" // } } } ``` This makes it safe to forward errors directly to Sentry, Datadog, or any error-tracking service. ## `Error.cause` chaining All SDK errors preserve the original cause via the standard `Error.cause` property — useful for debugging the exact failure at each layer: ```typescript theme={null} catch (err) { if (err instanceof DeepIDVError) { console.error('SDK error:', err.message); console.error('Caused by:', err.cause); // original fetch error, ZodError, etc. } } ``` ## Recommended try/catch pattern ```typescript theme={null} import { DeepIDV, ValidationError, AuthenticationError, RateLimitError, TimeoutError, NetworkError, DeepIDVError, } from '@deepidv/server'; try { const result = await client.document.scan({ image: buffer }); console.log(result.fullName); } catch (err) { if (err instanceof ValidationError) { console.error('Invalid input:', err.message); // fix your code } else if (err instanceof AuthenticationError) { console.error('Auth failed:', err.redactedKey); // check config } else if (err instanceof RateLimitError) { console.error(`Rate limited, retry after ${err.retryAfter}s`); // back off } else if (err instanceof TimeoutError) { console.error('Timed out'); // retry or raise the timeout } else if (err instanceof NetworkError) { console.error('Network error:', err.message); // retry later } else if (err instanceof DeepIDVError) { console.error(`API error ${err.status}: ${err.message}`); // other API error } else { throw err; // not from the SDK } } ``` # Server SDK Overview Source: https://docs.deepidv.com/integrate/sdks/typescript/server/overview @deepidv/server is a typed, backend-first TypeScript SDK for the deepidv identity verification API — sessions, document and face primitives, identity verification, and silent screening. `@deepidv/server` is the official backend-first TypeScript SDK for the [deepidv](https://api.deepidv.com) identity verification API. It wraps every REST endpoint in a typed, autocompleting client so you can create hosted verification sessions, scan documents, compare faces, run full identity verification, and screen individuals — without hand-writing HTTP, auth, retries, or file uploads.
document upload,
selfie capture,
liveness check User->>Server: Redirect back to redirectUrl
?status=SUBMITTED Server->>SDK: client.sessions.retrieve(sessionId) SDK->>API: GET /v1/sessions/{id} API-->>SDK: { sessionRecord, user, resourceLinks } SDK-->>Server: SessionRetrieveResult Note over Server: Process verification results ``` ## Step 1 — Create a session ```typescript theme={null} const session = await client.sessions.create({ // Required fields firstName: 'Jane', lastName: 'Doe', email: 'jane@example.com', phone: '+15551234567', // Optional: redirect the user back to your app when done redirectUrl: 'https://yourapp.com/verification-complete', // Optional: your internal reference ID externalId: 'user_abc123', // Optional: trigger email / SMS invitations sendEmailInvite: true, sendPhoneInvite: false, // Optional: run a specific workflow workflowId: 'wf_standard_kyc', }); ``` The result contains the URL to send your user to: | Field | Type | Description | | ------------ | ---------------------- | ---------------------------------------- | | `id` | `string` | Unique session identifier | | `sessionUrl` | `string` | URL to send the user to for verification | | `externalId` | `string?` | Your external reference ID (if provided) | | `links` | `Array<{ url, type }>` | Associated resource links |
| Service | What it does | Price per use |
|---|---|---|
ID Verification |
Scans and validates government-issued identity documents | \$0.50 |
Face Liveness |
Confirms the applicant is a live person, not a photo or deepfake | \$0.05 |
Age Estimation |
Predicts the applicant's age from facial analysis | \$0.05 |
PEP & Sanctions |
Checks against global politically exposed persons and sanctions lists | \$0.40 |
Adverse Media |
Scans for negative press, legal issues, and public media mentions | \$0.40 |
Phone Verification |
Places a live call and verifies identity through a spoken voice prompt | \$0.40 |
Address Verification |
AI-powered conversation to confirm the applicant's location | \$0.50 |
Bank Statement Sync |
Pulls bank statements directly from the applicant's financial institution | \$1.10 |
AI Bank Statement Analysis |
AI-driven breakdown of income, spending, and affordability | \$0.95 |
Title Search |
Looks up property title records for ownership and lien data | \$0.80 |
Document Fraud Analysis |
AI analysis of uploaded documents for tampering or forgery | \$0.40 |
Document Upload |
Collects supporting documents from the applicant | \$0.05 |
Custom Prompt Picture |
Requests a specific photo based on a prompt you define | \$0.05 |
Custom Form |
Custom questions, fields, and file uploads in the verification flow | \$0.05 |
E-Signature |
Collects a legally binding electronic signature from the applicant | \$0.10 |
Credit Check |
Pulls credit reports from major bureaus | Contact Sales |