Handling Errors

Learn how to handle errors gracefully using the MAES Platform SDK.

SDK Error Classes

The SDK provides typed error classes for different scenarios:

import {
  MaesClient,
  MaesApiError,
  MaesAuthenticationError,
  MaesPermissionError,
  MaesNotFoundError,
  MaesRateLimitError,
  MaesValidationError,
  MaesConnectionError,
} from '@nuvoni/maes-sdk';

Basic Error Handling

import { MaesClient, MaesNotFoundError } from '@nuvoni/maes-sdk';

const client = new MaesClient({
  apiKey: process.env.MAES_API_KEY!,
  projectId: process.env.MAES_PROJECT_ID!,
});

try {
  const card = await client.cards.get('card-id');
} catch (error) {
  if (error instanceof MaesNotFoundError) {
    console.log('Card not found');
  } else {
    throw error;
  }
}

Handling Specific Errors

import {
  MaesClient,
  MaesNotFoundError,
  MaesAuthenticationError,
  MaesPermissionError,
  MaesRateLimitError,
  MaesValidationError,
  MaesApiError,
} from '@nuvoni/maes-sdk';

async function safeEnableCard(cardId: string) {
  try {
    return await client.cards.enable(cardId);
  } catch (error) {
    if (error instanceof MaesNotFoundError) {
      console.error('Card not found');
      return null;
    }

    if (error instanceof MaesAuthenticationError) {
      console.error('Invalid API key - check your configuration');
      throw error;
    }

    if (error instanceof MaesPermissionError) {
      console.error('No permission to access this resource');
      throw error;
    }

    if (error instanceof MaesRateLimitError) {
      console.error('Rate limited - waiting before retry');
      await sleep(60000);
      return safeEnableCard(cardId); // Retry
    }

    if (error instanceof MaesValidationError) {
      console.error('Validation error:', error.message);
      return null;
    }

    if (error instanceof MaesApiError) {
      console.error(`API error ${error.status}: ${error.code}`);
      throw error;
    }

    throw error;
  }
}

Error Properties

All API errors have these properties:

try {
  await client.cards.get('invalid-id');
} catch (error) {
  if (error instanceof MaesApiError) {
    console.log(error.status); // HTTP status code (401, 403, 404, etc.)
    console.log(error.code); // Error code ('error.not_found', etc.)
    console.log(error.message); // Human-readable message
    console.log(error.body); // Raw API response
  }
}

Retry with Exponential Backoff

async function fetchWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
): Promise<T> {
  const delays = [1000, 5000, 30000]; // 1s, 5s, 30s

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      // Don't retry client errors (except rate limit)
      if (error instanceof MaesApiError) {
        if (error.status === 429) {
          // Rate limited - retry
          console.log(`Rate limited. Retrying in ${delays[attempt]}ms...`);
          await sleep(delays[attempt]);
          continue;
        }

        if (error.status >= 400 && error.status < 500) {
          throw error; // Don't retry client errors
        }
      }

      // Retry server errors
      if (attempt === maxRetries - 1) throw error;
      await sleep(delays[attempt]);
    }
  }

  throw new Error('Max retries exceeded');
}

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// Usage
const card = await fetchWithRetry(() => client.cards.get('card-id'));

HTTP Status Codes

Code	Error Class	Description
400	MaesValidationError	Invalid parameters
401	MaesAuthenticationError	Missing or invalid API key
403	MaesPermissionError	No access to resource
404	MaesNotFoundError	Resource doesn't exist
429	MaesRateLimitError	Rate limit exceeded
5xx	MaesApiError	Server error

Common Error Codes

Code	Description
error.unauthorized	Invalid API key
error.forbidden	No permission
error.not_found	Resource not found
error.card_not_found	Card doesn't exist
error.card_already_active	Card already activated
error.validation	Request validation failed
error.rate_limit	Rate limit exceeded

Connection Errors

Handle network issues separately:

import { MaesConnectionError } from '@nuvoni/maes-sdk';

try {
  await client.cards.list();
} catch (error) {
  if (error instanceof MaesConnectionError) {
    console.error('Network error:', error.message);
    // Retry or show offline message
  }
}

Debugging Tips

1. Log errors with context — Include card ID, operation type
2. Check error.code — Use specific error codes for handling
3. Use sandbox for testing error scenarios
4. Check audit logs in the dashboard
5. Verify API key permissions and environment