Error Handling

The Humanmark SDK handles most errors internally with automatic retries. You only need to handle a few common cases.

Common Error Cases

USER_CANCELLED

User closed verification modal.

CHALLENGE_EXPIRED

Challenge timed out. Create a new challenge token.

Other Errors

SDK has already retried. Log for debugging and show a generic message.

error-handling.js

import { HumanmarkSdk, ErrorCode } from '@humanmark/sdk-js';

try {
  const receipt = await sdk.verify();
  await submitToBackend(receipt);
} catch (error) {
  switch (error.code) {
    case ErrorCode.USER_CANCELLED:
      // User cancelled - allow them to retry
      showMessage('Verification cancelled');
      break;
      
    case ErrorCode.CHALLENGE_EXPIRED:
      // Challenge expired - create new one
      await refreshChallenge();
      break;
      
    default:
      // Other errors - show generic message
      showError('Verification failed. Please try again.');
      console.error('Error:', error);
  }
}

Error Code Reference

User Actions

Error Code	Description	Action Required
`USER_CANCELLED`	User closed the verification modal	Allow user to retry when ready

Challenge Errors

Error Code	Description	Action Required
`CHALLENGE_EXPIRED`	Challenge token has expired	Create a new challenge token
`NO_ACTIVE_CHALLENGE`	No challenge available	Initialize SDK with valid challenge
`INVALID_CHALLENGE_FORMAT`	Invalid challenge token format	Verify challenge token from backend

Configuration Errors

Error Code	Description	Action Required
`INVALID_CONFIG`	Invalid SDK configuration	Check SDK initialization parameters
`INVALID_API_KEY`	API key is missing or invalid	Verify your API key is correct
`MISSING_CREDENTIALS`	Missing required credentials	Provide all required credentials

API Errors

Error Code	Description	Action Required
`INVALID_API_KEY_OR_SECRET`	Invalid API credentials (401)	Check API key and secret
`RATE_LIMITED`	Too many requests (429)	Implement exponential backoff
`SERVER_ERROR`	Server error (5xx)	Retry after a delay

Network Errors

Error Code	Description	Action Required
`NETWORK_ERROR`	Network request failed	Check internet connection
`TIMEOUT`	Request timed out	Check network latency
`INVALID_RESPONSE`	Invalid server response format	Contact support if persists