Error Handling

Error Response Format

When an error occurs, Vellosim API returns a JSON response with error details:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  },
  "statusCode": 400
}

Common Error Codes

Authentication Errors

Error Code	Status	Description	Solution
UNAUTHORIZED	401	Missing or invalid API key	Check your API key and ensure it’s included in the Authorization header
FORBIDDEN	403	Valid key but insufficient permissions	Contact support to upgrade your permissions
RATE_LIMIT_EXCEEDED	429	Too many requests	Implement rate limiting and retry with exponential backoff

Validation Errors

Error Code	Status	Description	Solution
INVALID_PARAMETERS	400	Missing or invalid request parameters	Review the required parameters for the endpoint
INVALID_REGION_CODE	400	Invalid region code provided	Use valid region codes from the regions endpoint
INVALID_PACKAGE_CODE	400	Package code doesn’t exist	Verify package code from packages endpoint

Business Logic Errors

Error Code	Status	Description	Solution
INSUFFICIENT_BALANCE	400	Wallet balance too low	Top up your wallet balance
PACKAGE_UNAVAILABLE	400	Package is temporarily unavailable	Try a different package or retry later
ORDER_NOT_FOUND	404	Order ID doesn’t exist	Verify the order ID
DUPLICATE_ORDER	409	Order already exists	Check your order history

Server Errors

Error Code	Status	Description	Solution
INTERNAL_ERROR	500	Internal server error	Retry the request or contact support
SERVICE_UNAVAILABLE	503	Service temporarily unavailable	Wait and retry with exponential backoff

Error Handling Examples

Basic Error Handling

async function getPackages(regionCode: string, regionType: string) {
  try {
    const response = await fetch(
      `https://api.vellosim.com/api/esim/packages?regionCode=${regionCode}&regionType=${regionType}`,
      {
        headers: {
          'X-API-Key': `API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('Failed to fetch packages:', error);
    throw error;
  }
}

Advanced Error Handling with Retry Logic

async function makeRequestWithRetry(
  url: string,
  options: RequestInit,
  maxRetries: number = 3
) {
  let lastError: Error;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      // Handle different error types
      if (!response.ok) {
        const error = await response.json();
        
        // Don't retry client errors (4xx)
        if (response.status >= 400 && response.status < 500) {
          throw new Error(error.error.message);
        }
        
        // Retry server errors (5xx) with exponential backoff
        if (response.status >= 500) {
          const delay = Math.pow(2, attempt) * 1000;
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
      }
      
      return await response.json();
      
    } catch (error) {
      lastError = error as Error;
      
      // Don't retry on last attempt
      if (attempt === maxRetries - 1) {
        break;
      }
      
      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  
  throw lastError!;
}

User-Friendly Error Messages

Create a mapping for user-friendly error messages:

const ERROR_MESSAGES = {
  UNAUTHORIZED: 'Authentication failed. Please check your credentials.',
  INSUFFICIENT_BALANCE: 'Your account balance is too low. Please top up your wallet.',
  INVALID_PACKAGE_CODE: 'The selected package is not available. Please choose another.',
  RATE_LIMIT_EXCEEDED: 'Too many requests. Please wait a moment and try again.',
  PACKAGE_UNAVAILABLE: 'This package is temporarily unavailable. Please try another.',
  INTERNAL_ERROR: 'Something went wrong on our end. Please try again later.',
  SERVICE_UNAVAILABLE: 'Service is temporarily unavailable. Please try again later.'
};

function getUserFriendlyMessage(errorCode: string): string {
  return ERROR_MESSAGES[errorCode] || 'An unexpected error occurred. Please try again.';
}

// Usage
try {
  await purchaseEsim(packageCode);
} catch (error) {
  const message = getUserFriendlyMessage(error.code);
  showErrorToUser(message);
}

Validation Before API Calls

Validate data before making API requests to reduce errors:

function validatePurchaseRequest(data) {
  const errors = [];
  
  if (!data.packageCode) {
    errors.push('Package code is required');
  }
  
  if (!data.paymentMethod) {
    errors.push('Payment method is required');
  } else if (!['wallet', 'card'].includes(data.paymentMethod)) {
    errors.push('Invalid payment method');
  }
  
  if (!data.packageType) {
    errors.push('Package type is required');
  }
  
  if (errors.length > 0) {
    throw new Error(errors.join(', '));
  }
}

// Usage
try {
  validatePurchaseRequest(purchaseData);
  await purchaseEsim(purchaseData);
} catch (error) {
  handleValidationError(error);
}

Logging and Monitoring

Implement proper logging for debugging:

function logApiError(error, context) {
  console.error({
    timestamp: new Date().toISOString(),
    error: error.message,
    code: error.code,
    statusCode: error.statusCode,
    context: context,
    stack: error.stack
  });
  
  // Send to monitoring service (e.g., Sentry, DataDog)
  if (window.Sentry) {
    Sentry.captureException(error, {
      extra: context
    });
  }
}

Best Practices

Implement Exponential Backoff

For transient errors and rate limits, use exponential backoff to automatically retry failed requests with increasing delays.

Don't Retry Client Errors

Never retry 4xx errors (except 429) as they indicate client-side issues that won’t be resolved by retrying.

Log Errors Properly

Log all errors with context to help debugging. Include request parameters, timestamps, and user identifiers (without sensitive data).

Show User-Friendly Messages

Don’t expose technical error messages to end users. Create friendly, actionable error messages instead.

Monitor Error Rates

Track error rates and patterns to identify issues early and improve your integration.

Graceful Degradation

When APIs fail, provide fallback options or cached data when possible to maintain user experience.

Getting Started

Integration Guide

others

Error Response Format

Common Error Codes

Authentication Errors

Validation Errors

Business Logic Errors

Server Errors

Error Handling Examples

Basic Error Handling

Advanced Error Handling with Retry Logic

User-Friendly Error Messages

Validation Before API Calls

Logging and Monitoring

Best Practices

Next Steps

Webhooks

API Reference

Getting Started

Integration Guide

others

​Error Response Format

​Common Error Codes

​Authentication Errors

​Validation Errors

​Business Logic Errors

​Server Errors

​Error Handling Examples

​Basic Error Handling

​Advanced Error Handling with Retry Logic

​User-Friendly Error Messages

​Validation Before API Calls

​Logging and Monitoring

​Best Practices

​Next Steps

Webhooks

API Reference

Error Response Format

Common Error Codes

Authentication Errors

Validation Errors

Business Logic Errors

Server Errors

Error Handling Examples

Basic Error Handling

Advanced Error Handling with Retry Logic

User-Friendly Error Messages

Validation Before API Calls

Logging and Monitoring

Best Practices

Next Steps