Error Handling

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more validation errors occurred",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid",
        "code": "INVALID_EMAIL_FORMAT"
      },
      {
        "field": "phone",
        "message": "Phone number is required",
        "code": "REQUIRED_FIELD"
      }
    ],
    "requestId": "req_123456789",
    "timestamp": "2024-01-15T10:30:00Z",
    "documentation": "https://developers.bigledger.com/errors#validation-error"
  },
  "meta": {
    "requestId": "req_123456789",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication credentials were not provided or are invalid",
    "details": [
      {
        "field": "authorization",
        "message": "API key is missing or invalid",
        "code": "INVALID_API_KEY"
      }
    ]
  }
}

// Ensure proper header format
const headers = {
  'Authorization': 'Bearer blg_live_sk_1234567890abcdef',
  'Content-Type': 'application/json',
  'X-Company-Id': 'company_abc123'
};

// Verify API key is active
const response = await fetch('/api/v1/auth/verify', { headers });

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to access this resource",
    "details": [
      {
        "required_scope": "write:invoices",
        "current_scopes": ["read:invoices", "read:customers"]
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "items[0].quantity",
        "message": "Quantity must be greater than 0",
        "code": "MIN_VALUE",
        "value": -5,
        "constraint": ">= 1"
      },
      {
        "field": "dueDate",
        "message": "Due date must be after invoice date",
        "code": "DATE_CONSTRAINT",
        "value": "2024-01-10",
        "constraint": "> 2024-01-15"
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "BUSINESS_RULE_VIOLATION",
    "message": "Invoice cannot be modified after it has been paid",
    "details": [
      {
        "rule": "PAID_INVOICE_IMMUTABLE",
        "invoiceId": "inv_123456789",
        "invoiceStatus": "paid",
        "paidAt": "2024-01-10T14:30:00Z"
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found",
    "details": [
      {
        "resource": "customer",
        "id": "cust_invalid123",
        "field": "customerId"
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Resource already exists with the same identifier",
    "details": [
      {
        "resource": "customer",
        "field": "email",
        "value": "existing@company.com",
        "existingId": "cust_789012345"
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after the specified time",
    "details": [
      {
        "limit": 1000,
        "remaining": 0,
        "resetTime": "2024-01-15T11:00:00Z",
        "retryAfter": 300
      }
    ]
  }
}

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642248000
Retry-After: 300

{
  "success": false,
  "error": {
    "code": "EINVOICE_VALIDATION_FAILED",
    "message": "E-invoice validation failed against government schema",
    "details": [
      {
        "code": "BR-MY-01",
        "message": "Buyer tax identification number is required for B2B transactions",
        "field": "AccountingCustomerParty.Party.PartyTaxScheme.CompanyID",
        "severity": "error",
        "xpath": "/Invoice/cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID"
      }
    ],
    "governmentResponse": {
      "portal": "myinvois",
      "validationId": "val_123456",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Payment amount exceeds available credit limit",
    "details": [
      {
        "customerId": "cust_123456789",
        "currentBalance": 15000.00,
        "creditLimit": 20000.00,
        "availableCredit": 5000.00,
        "requestedAmount": 7500.00
      }
    ]
  }
}

class RetryHandler {
  constructor(maxRetries = 3, baseDelay = 1000) {
    this.maxRetries = maxRetries;
    this.baseDelay = baseDelay;
  }
  
  async executeWithRetry(operation, retryableErrors = ['RATE_LIMIT_EXCEEDED', 'SERVICE_UNAVAILABLE']) {
    let lastError;
    
    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
      try {
        return await operation();
      } catch (error) {
        lastError = error;
        
        // Don't retry client errors (except rate limiting)
        if (error.status < 500 && !retryableErrors.includes(error.code)) {
          throw error;
        }
        
        if (attempt === this.maxRetries) {
          throw error;
        }
        
        // Calculate delay with exponential backoff
        const delay = error.retryAfter 
          ? error.retryAfter * 1000 
          : this.baseDelay * Math.pow(2, attempt);
        
        console.log(`Attempt ${attempt + 1} failed, retrying in ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
    
    throw lastError;
  }
}

// Usage
const retryHandler = new RetryHandler();
const invoice = await retryHandler.executeWithRetry(
  () => client.invoices.create(invoiceData)
);

// Client-side validation to reduce API errors
function validateInvoiceData(invoiceData) {
  const errors = [];
  
  // Required fields
  if (!invoiceData.customerId) {
    errors.push({ field: 'customerId', message: 'Customer ID is required' });
  }
  
  if (!invoiceData.items || invoiceData.items.length === 0) {
    errors.push({ field: 'items', message: 'At least one item is required' });
  }
  
  // Date validation
  if (invoiceData.dueDate && invoiceData.invoiceDate) {
    const invoiceDate = new Date(invoiceData.invoiceDate);
    const dueDate = new Date(invoiceData.dueDate);
    
    if (dueDate <= invoiceDate) {
      errors.push({ 
        field: 'dueDate', 
        message: 'Due date must be after invoice date' 
      });
    }
  }
  
  // Item validation
  invoiceData.items?.forEach((item, index) => {
    if (!item.description) {
      errors.push({ 
        field: `items[${index}].description`, 
        message: 'Item description is required' 
      });
    }
    
    if (!item.quantity || item.quantity <= 0) {
      errors.push({ 
        field: `items[${index}].quantity`, 
        message: 'Item quantity must be greater than 0' 
      });
    }
    
    if (!item.unitPrice || item.unitPrice < 0) {
      errors.push({ 
        field: `items[${index}].unitPrice`, 
        message: 'Item unit price must be greater than or equal to 0' 
      });
    }
  });
  
  return errors;
}

// Use validation before API call
async function createInvoice(invoiceData) {
  const validationErrors = validateInvoiceData(invoiceData);
  if (validationErrors.length > 0) {
    return {
      success: false,
      error: 'validation',
      details: validationErrors
    };
  }
  
  // Proceed with API call
  return await createInvoiceWithErrorHandling(invoiceData);
}

class APIErrorLogger {
  constructor(client) {
    this.client = client;
    this.errorCounts = new Map();
    this.lastErrors = [];
  }
  
  logError(error, context = {}) {
    const errorData = {
      timestamp: new Date().toISOString(),
      code: error.code,
      message: error.message,
      requestId: error.requestId,
      context: context,
      stackTrace: error.stack
    };
    
    // Store for analysis
    this.lastErrors.push(errorData);
    if (this.lastErrors.length > 100) {
      this.lastErrors.shift(); // Keep only last 100 errors
    }
    
    // Count error types
    const count = this.errorCounts.get(error.code) || 0;
    this.errorCounts.set(error.code, count + 1);
    
    // Log to external service (e.g., Sentry, LogRocket)
    this.sendToLoggingService(errorData);
    
    // Alert on critical errors
    if (this.isCriticalError(error)) {
      this.sendAlert(errorData);
    }
  }
  
  isCriticalError(error) {
    const criticalErrors = [
      'AUTHENTICATION_FAILED',
      'SERVICE_UNAVAILABLE',
      'INTERNAL_SERVER_ERROR'
    ];
    return criticalErrors.includes(error.code);
  }
  
  getErrorStats() {
    return {
      totalErrors: this.lastErrors.length,
      errorsByType: Object.fromEntries(this.errorCounts),
      recentErrors: this.lastErrors.slice(-10)
    };
  }
}

# Test authentication
curl -X GET "https://api.bigledger.com/v1/auth/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Company-Id: YOUR_COMPANY_ID"

// Rate limiting handler
class RateLimitHandler {
  constructor() {
    this.queue = [];
    this.processing = false;
    this.requestsPerSecond = 10; // Adjust based on your limit
  }
  
  async makeRequest(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.processQueue();
    });
  }
  
  async processQueue() {
    if (this.processing || this.queue.length === 0) return;
    
    this.processing = true;
    
    while (this.queue.length > 0) {
      const { requestFn, resolve, reject } = this.queue.shift();
      
      try {
        const result = await requestFn();
        resolve(result);
      } catch (error) {
        if (error.code === 'RATE_LIMIT_EXCEEDED') {
          // Re-queue the request
          this.queue.unshift({ requestFn, resolve, reject });
          await new Promise(r => setTimeout(r, error.retryAfter * 1000));
          continue;
        }
        reject(error);
      }
      
      // Delay between requests
      await new Promise(r => setTimeout(r, 1000 / this.requestsPerSecond));
    }
    
    this.processing = false;
  }
}

// Network error handler
async function makeRequestWithNetworkRetry(requestFn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.code === 'NETWORK_ERROR' && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}