Error Handling

The SDK throws typed errors that you can catch and handle appropriately.

Error codes

Code	HTTP Status	Description
VALIDATION_ERROR	400	Invalid request parameters
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource does not exist
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error — retry with backoff

Handling errors

error-handling.ts

try {
  const session = await client.createSession({
    referenceId: 'user-12345',
  });
} catch (error) {
  if (error instanceof HeuristikError) {
    switch (error.code) {
      case 'VALIDATION_ERROR':
        console.error('Invalid input:', error.details);
        break;
      case 'RATE_LIMITED':
        console.warn('Rate limited — retry after', error.retryAfter, 'seconds');
        break;
      case 'UNAUTHORIZED':
        console.error('Check your API key');
        break;
      default:
        console.error('Unexpected error:', error.message);
    }
  }
}

Do not ignore errors

Always wrap SDK calls in try/catch blocks. Unhandled errors may crash your application or leave verifications in an inconsistent state.

Retry strategy

For transient errors (429, 500, 503), implement exponential backoff:

retry.ts

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
  throw new Error('Unreachable');
}

Idempotency

Use referenceId as an idempotency key. If you retry a createSession call with the same referenceId, the API returns the existing session instead of creating a duplicate.