Error Handling in the Vouch SDK: Codes and Patterns

All Vouch SDK methods return Promises and throw errors as Axios errors when something goes wrong. This means you can use standard try/catch blocks to handle failures, inspect the HTTP status code, and surface meaningful messages to your users. Understanding the error surface helps you build resilient integrations that degrade gracefully under failure conditions.

Standard Error Handling Pattern

Wrap every SDK call in a try/catch block. Axios errors expose three distinct shapes depending on where the failure occurred: a server response, a network-level failure, or an unexpected client-side error.

import Vouch from 'vouch-sdk';

const vouch = new Vouch({ apiKey: 'your_api_key' });

try {
  const agreement = await vouch.escrow.status('invalid_id');
} catch (error: any) {
  if (error.response) {
    // The server responded with a non-2xx status code
    const status: number = error.response.status;
    const message: string = error.response.data?.message ?? 'Unknown server error';
    console.error(`HTTP ${status}: ${message}`);
  } else if (error.request) {
    // The request was sent but no response was received
    console.error('Network error — check your internet connection');
  } else {
    // Something went wrong setting up the request
    console.error('Unexpected error:', error.message);
  }
}

HTTP Error Reference

The table below lists every HTTP status code the Vouch API returns, its cause, and the recommended resolution.

Code	Cause	Resolution
`400`	Bad Request — missing required fields or invalid file format	Check all required parameters are present; ensure images are JPEG or PNG and under 5 MB
`401`	Unauthorized — invalid or missing API key	Verify your `x-api-key` value is correct and has not expired
`404`	Not Found — agreement ID, milestone ID, or other resource does not exist	Double-check the ID you are passing matches a resource you created
`409`	Conflict — duplicate action (e.g., milestone already confirmed)	Check the current resource state before performing write operations
`413`	Payload Too Large — uploaded file exceeds 5 MB	Compress or resize the image before uploading
`500`	Internal Server Error	Retry with exponential backoff; contact support if the error persists
`503`	Service Unavailable	Wait briefly, then retry; check the Vouch status page for outages

Identity Verification Errors

When an identity check fails, the verification result will have identityVerified: false along with a rejection_reason field that tells you exactly why the check did not pass. Inspect this field to present actionable feedback to your user rather than a generic failure message.

const result = await vouch.identity.verify({
  documentImage: documentBase64,
  selfieImage: selfieBase64,
});

if (!result.data.identityVerified) {
  const reason = result.data.rejection_reason;

  switch (reason) {
    case 'face_not_found':
      // No face was detected in the selfie or document photo
      console.warn('No face detected. Ask the user to retake the photo in good lighting.');
      break;

    case 'liveness_failed':
      // The liveness check determined the selfie may not be a live person
      console.warn('Liveness check failed. Ask the user to use the live camera capture.');
      break;

    case 'match_below_threshold':
      // Face similarity score fell below the 90% ArcFace threshold
      console.warn('Face match too low. Ensure the selfie clearly shows the user\'s face.');
      break;

    case 'document_unreadable':
      // Reducto AI could not extract fields from the document image
      console.warn('Document unreadable. Ask the user to upload a clearer, unobstructed photo.');
      break;

    default:
      console.warn(`Verification failed: ${reason}`);
  }
}

Identity verification errors are not HTTP errors — the API returns a 200 response with identityVerified: false. Check the rejection_reason field, not the HTTP status code, to understand why a verification failed.

Fraud Assessment Behavior

When the Vouch fraud engine encounters an internal error during scoring, it deliberately defaults to an AMBER flag rather than PASS. This fail-safe means the engine never auto-approves a transaction when it cannot complete a full assessment. Your integration should treat AMBER as requiring human review, not as a soft pass.

const fraudResult = await vouch.fraud.assess({
  userId: 'user_123',
  transactionData: { amount: 50000, currency: 'NGN' },
});

switch (fraudResult.data.flag) {
  case 'GREEN':
    // Clean signal — proceed normally
    break;

  case 'AMBER':
    // Engine error OR borderline signals — requires human review
    if (fraudResult.data.engineError) {
      console.warn('Fraud engine encountered an error. Defaulting to manual review.');
    }
    // Route to your review queue regardless of the cause
    triggerManualReview(fraudResult);
    break;

  case 'RED':
    // Clear fraud signals detected — block the transaction
    blockTransaction(fraudResult);
    break;
}

Never treat an AMBER result as an implicit approval. When the fraud engine errors, it returns AMBER as a conservative default. Always route AMBER results to a human reviewer or hold queue.

Retry Strategy

Apply different retry strategies depending on the error class. Retrying a 4xx error is almost always wrong — the request itself is malformed, so sending it again will produce the same failure.

5xx errors — the server failed; retry with exponential backoff
4xx errors — the client sent a bad request; fix the request before resending
Network errors — retry with backoff; the server may not have received the request

The following utility wraps any async SDK call with configurable retries and exponential backoff:

async function withRetry<T>(
  fn: () => Promise<T>,
  maxAttempts = 3,
  baseDelayMs = 500,
): Promise<T> {
  let lastError: unknown;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      lastError = error;

      const status: number | undefined = error.response?.status;

      // Never retry client errors — fix the request instead
      if (status !== undefined && status >= 400 && status < 500) {
        throw error;
      }

      if (attempt < maxAttempts) {
        const delay = baseDelayMs * 2 ** (attempt - 1); // 500ms, 1000ms, 2000ms …
        console.warn(`Attempt ${attempt} failed (${status ?? 'network'}). Retrying in ${delay}ms…`);
        await new Promise(r => setTimeout(r, delay));
      }
    }
  }

  throw lastError;
}

// Usage
const agreement = await withRetry(() => vouch.escrow.status(agreementId));

What if the server returns 503 during a critical escrow operation?

A 503 Service Unavailable response means Vouch’s infrastructure is temporarily unable to handle your request. Use exponential backoff and retry up to three times. If the error persists beyond your retry budget, surface a user-friendly message and check the Vouch status page. Avoid retrying indefinitely — use a maximum attempt cap and alert your team if the threshold is exceeded.

Should I retry identity verification on failure?

Only retry on network errors or 5xx responses. If the identity check returned identityVerified: false with a rejection_reason, retrying the same images will produce the same result. Prompt the user to retake their photo or document scan based on the specific rejection reason before submitting again.

Log the triggered signals from fraud assessments (available in fraudResult.data.signals) alongside the flag value. These signal arrays are invaluable for debugging false positives and tuning your review workflows over time.

Get Started

Core Concepts

SDK Reference

Guides

Resources

Error Handling in the Vouch SDK: Codes and Patterns

Standard Error Handling Pattern

HTTP Error Reference

Identity Verification Errors

Fraud Assessment Behavior

Retry Strategy

​Standard Error Handling Pattern

​HTTP Error Reference

​Identity Verification Errors

​Fraud Assessment Behavior

​Retry Strategy

Standard Error Handling Pattern

HTTP Error Reference

Identity Verification Errors

Fraud Assessment Behavior

Retry Strategy