Error Codes

Comprehensive guide to error codes returned by the eXlr8 API and how to handle them.

Error Response Format

All API errors follow a consistent format:

{
  "error": "Human-readable error message",
  "errCode": "ERROR_CODE"
}

General Error Codes

HTTP 400 - Bad Request

Error Code	Description	Common Causes
BAD_REQUEST	The request was invalid or malformed	Missing required fields, incorrect data format, invalid JSON

Example:

{
  "error": "invalid variant ID",
  "errCode": "BAD_REQUEST"
}

HTTP 401 - Unauthorized

Error Code	Description	Common Causes
UNAUTHORIZED	Authentication failed	Invalid credentials, missing headers, expired tokens

Example:

{
  "error": "unauthenticated",
  "errCode": "UNAUTHORIZED"
}

HTTP 403 - Forbidden

Error Code	Description	Common Causes
FORBIDDEN	Insufficient permissions	Accessing resources outside your scope, IP restrictions

Example:

{
  "error": "forbidden: param: admin user does not have access to DP: INVALID_DP_ID",
  "errCode": "FORBIDDEN"
}

HTTP 404 - Not Found

Error Code	Description	Common Causes
RECORD_NOT_FOUND	Requested resource not found	Invalid IDs, deleted resources, typos in parameters

Examples:

{
  "error": "Order not found",
  "errCode": "RECORD_NOT_FOUND"
}

{
  "error": "product not found for dpID: YOUR_DP_ID, productID: PRODUCT_ID",
  "errCode": "RECORD_NOT_FOUND"
}

HTTP 409 - Conflict

Error Code	Description	Common Causes
CONFLICT	Request conflicts with current state	Duplicate external references, concurrent modifications

Example:

{
  "error": "order with externalRefID already exist",
  "errCode": "CONFLICT"
}

HTTP 422 - Unprocessable Entity

Error Code	Description	Common Causes
UNPROCESSABLE_ENTITY	Valid request but semantic errors	Business logic violations, invalid combinations

Example:

{
  "error": "Cannot process order for inactive product",
  "errCode": "UNPROCESSABLE_ENTITY"
}

HTTP 500 - Internal Server Error

Error Code	Description	Common Causes
INTERNAL_SERVER_ERROR	Unexpected server error	Server issues, temporary outages, system problems

Example:

{
  "error": "An unexpected error occurred",
  "errCode": "INTERNAL_SERVER_ERROR"
}

Business Logic Error Codes

Order-Related Errors

Error Code	Description	Resolution
INSUFFICIENT_BALANCE	Not enough wallet balance	Top up wallet or reduce order amount
OUT_OF_STOCK	Product variant unavailable	Choose different variant or try later

Examples:

{
  "error": "Insufficient wallet balance for this order",
  "errCode": "INSUFFICIENT_BALANCE"
}

{
  "error": "Product variant is out of stock",
  "errCode": "OUT_OF_STOCK"
}

Error Handling Best Practices

1. Implement Retry Logic

async function apiCallWithRetry(apiCall, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      const errorData = await error.response?.json();
      
      // Don't retry on client errors (4xx)
      if (error.response?.status >= 400 && error.response?.status < 500) {
        throw error;
      }
      
      // Retry on server errors (5xx) with exponential backoff
      if (attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      throw error;
    }
  }
}

2. Specific Error Handling

async function handleApiError(error) {
  const errorData = await error.response?.json();
  
  switch (errorData?.errCode) {
    case 'INSUFFICIENT_BALANCE':
      // Redirect to top-up page or show balance warning
      await handleInsufficientBalance();
      break;
      
    case 'OUT_OF_STOCK':
      // Show alternative products or notify when back in stock
      await handleOutOfStock(errorData.productID);
      break;
      
    case 'UNAUTHORIZED':
      // Refresh credentials or redirect to login
      await refreshCredentials();
      break;
      
    case 'RECORD_NOT_FOUND':
      // Show user-friendly "not found" message
      showNotFoundMessage();
      break;
      
    case 'INTERNAL_SERVER_ERROR':
      // Log error and show generic error message
      logError(errorData);
      showGenericErrorMessage();
      break;
      
    default:
      // Handle unknown errors
      logError(errorData);
      showGenericErrorMessage();
  }
}

3. Error Logging

class ErrorLogger {
  static logError(error, context = {}) {
    const errorLog = {
      timestamp: new Date().toISOString(),
      errorCode: error.errCode,
      errorMessage: error.error,
      context: context,
      userAgent: navigator.userAgent,
      url: window.location.href
    };
    
    // Send to your logging service
    console.error('API Error:', errorLog);
    
    // Optional: Send to external logging service
    // await sendToLoggingService(errorLog);
  }
}

Error Prevention

1. Validation Before API Calls

function validateOrderRequest(orderData) {
  const errors = [];
  
  if (!orderData.dpID) {
    errors.push('dpID is required');
  }
  
  if (!orderData.variantID || !orderData.variantID.startsWith('VAR-')) {
    errors.push('Valid variantID is required');
  }
  
  if (!orderData.externalRefID || orderData.externalRefID.length < 1) {
    errors.push('externalRefID is required and must be unique');
  }
  
  if (errors.length > 0) {
    throw new Error(`Validation failed: ${errors.join(', ')}`);
  }
}

2. Balance Verification

async function validateSufficientBalance(orderAmount) {
  const balance = await getWalletBalance();
  
  if (balance.balance < orderAmount) {
    throw new Error('Insufficient balance for this order');
  }
}

Monitoring and Alerting

Error Rate Monitoring

class ErrorMonitor {
  constructor() {
    this.errorCounts = new Map();
    this.totalRequests = 0;
  }
  
  recordError(errCode) {
    this.errorCounts.set(errCode, (this.errorCounts.get(errCode) || 0) + 1);
  }
  
  recordRequest() {
    this.totalRequests++;
  }
  
  getErrorRate() {
    const totalErrors = Array.from(this.errorCounts.values()).reduce((a, b) => a + b, 0);
    return this.totalRequests > 0 ? (totalErrors / this.totalRequests) * 100 : 0;
  }
  
  getErrorBreakdown() {
    return Object.fromEntries(this.errorCounts);
  }
}

Common Solutions

Error Scenario	Solution
Authentication fails	Verify credentials, check header format
Orders not found	Verify dpID and orderID/externalRefID
Products not available	Check product catalog, verify variant IDs
Insufficient balance	Top up wallet or reduce order amount
Rate limiting	Implement exponential backoff and request queuing

Contact Support

If you encounter persistent errors or need assistance:

• Include: Error codes, request details, and timestamps
• Response Time: Typically within 24 hours for technical issues

Related Documentation

• Authentication - Authentication setup
• Support - Getting help and technical assistance