Error Handling

TokeniveError

All API errors throw TokeniveError with structured fields:

import { Tokenive, TokeniveError, ErrorCodes } from '@tokenive/sdk';

try {
  await client.proofRequests.create({ /* ... */ });
} catch (err) {
  if (err instanceof TokeniveError) {
    console.error('Status:', err.status);   // HTTP status code
    console.error('Code:', err.code);       // Machine-readable error code
    console.error('Message:', err.message); // Human-readable description
    console.error('Request ID:', err.requestId); // For support tickets
  }
}

Error Codes

Code	HTTP Status	Meaning
VALIDATION_ERROR	400	Invalid request parameters
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource doesn't exist
CONFLICT	409	Duplicate or conflicting state
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error
REQUEST_EXPIRED	—	Proof request has expired
ALREADY_CLAIMED	—	Request already claimed by a holder
INVALID_SIGNATURE	—	DID signature verification failed

Handling Specific Errors

import { TokeniveError, ErrorCodes } from '@tokenive/sdk';

try {
  await client.proofRequests.get(requestId);
} catch (err) {
  if (err instanceof TokeniveError) {
    switch (err.code) {
      case ErrorCodes.NOT_FOUND:
        console.log('Request does not exist');
        break;
      case ErrorCodes.UNAUTHORIZED:
        console.log('Check your API key');
        break;
      case ErrorCodes.RATE_LIMITED:
        console.log('Slow down, retry after a delay');
        break;
      default:
        console.error('Unexpected error:', err.message);
    }
  }
}

Retry Strategy

For transient errors (5xx, rate limits), implement exponential backoff:

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  let delay = 1000;
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (
        err instanceof TokeniveError &&
        (err.status >= 500 || err.code === ErrorCodes.RATE_LIMITED) &&
        attempt < maxRetries
      ) {
        await new Promise((r) => setTimeout(r, delay));
        delay *= 2;
        continue;
      }
      throw err;
    }
  }
  throw new Error('Unreachable');
}

// Usage
const result = await withRetry(() =>
  client.proofRequests.create({ /* ... */ })
);