Error Handling

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "type": "error_type",
    "details": {
      // Additional context-specific information
    },
    "request_id": "req_1NXWPnCo6bFb1KQto6C8OWvE",
    "timestamp": "2024-01-15T10:30:00Z",
    "documentation_url": "https://docs.stateset.com/errors/ERROR_CODE"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset_at": "2024-01-15T10:35:00Z",
      "retry_after": 300
    }
  }
}

class ErrorHandler {
  handle(error) {
    switch (error.code) {
      case 'INVALID_API_KEY':
        // Refresh API key or prompt for new one
        return this.refreshApiKey();
        
      case 'INSUFFICIENT_PERMISSIONS':
        // Inform user about permission requirements
        return this.showPermissionError(error.details);
        
      case 'VALIDATION_ERROR':
        // Show field-specific errors
        return this.showValidationErrors(error.details);
        
      case 'RATE_LIMITED':
        // Implement backoff and queue
        return this.queueRequest(error.details.retry_after);
        
      case 'INSUFFICIENT_INVENTORY':
        // Update UI with available quantity
        return this.updateInventory(error.details);
        
      default:
        // Generic error handling
        return this.showGenericError(error.message);
    }
  }
}

class CircuitBreaker {
  constructor(threshold = 5, timeout = 60000) {
    this.failureCount = 0;
    this.failureThreshold = threshold;
    this.timeout = timeout;
    this.state = 'CLOSED';
    this.nextAttempt = Date.now();
  }
  
  async call(fn) {
    if (this.state === 'OPEN') {
      if (Date.now() < this.nextAttempt) {
        throw new Error('Circuit breaker is OPEN');
      }
      this.state = 'HALF_OPEN';
    }
    
    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
  
  onSuccess() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }
  
  onFailure() {
    this.failureCount++;
    if (this.failureCount >= this.failureThreshold) {
      this.state = 'OPEN';
      this.nextAttempt = Date.now() + this.timeout;
    }
  }
}

class ErrorLogger {
  log(error, context) {
    const errorData = {
      timestamp: new Date().toISOString(),
      request_id: error.request_id,
      error_code: error.code,
      message: error.message,
      context: {
        user_id: context.userId,
        endpoint: context.endpoint,
        method: context.method,
        ...context
      },
      stack_trace: error.stack
    };
    
    // Send to logging service
    logger.error(errorData);
    
    // Track in analytics
    analytics.track('API_ERROR', errorData);
    
    // Alert on critical errors
    if (this.isCritical(error)) {
      alerting.notify(errorData);
    }
  }
  
  isCritical(error) {
    const criticalCodes = [
      'PAYMENT_FAILED',
      'SERVICE_UNAVAILABLE',
      'DATABASE_ERROR'
    ];
    return criticalCodes.includes(error.code);
  }
}

// Use idempotency keys to safely retry requests
const createOrder = async (orderData) => {
  const idempotencyKey = `order-${uuidv4()}`;
  
  try {
    return await api.post('/orders', orderData, {
      headers: {
        'Idempotency-Key': idempotencyKey
      }
    });
  } catch (error) {
    if (error.code === 'DUPLICATE_REQUEST') {
      // Return existing order from previous request
      return error.details.existing_resource;
    }
    throw error;
  }
};

class ResilientClient {
  async getProductWithFallback(productId) {
    try {
      // Try primary API
      return await this.api.get(`/products/${productId}`);
    } catch (error) {
      if (error.code === 'SERVICE_UNAVAILABLE') {
        // Fall back to cache
        const cached = await this.cache.get(`product:${productId}`);
        if (cached) {
          return { ...cached, from_cache: true };
        }
        
        // Fall back to secondary service
        return await this.secondaryApi.get(`/products/${productId}`);
      }
      throw error;
    }
  }
}

// Request
POST /v1/orders
{
  "customer_email": "invalid-email",
  "items": []
}

// Response (422)
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "type": "validation_error",
    "details": {
      "errors": [
        {
          "field": "customer_email",
          "message": "Invalid email format",
          "expected": "valid email address"
        },
        {
          "field": "items",
          "message": "At least one item is required",
          "expected": "non-empty array"
        }
      ]
    },
    "request_id": "req_abc123"
  }
}

// Request
POST /v1/customers
{
  "email": "existing@example.com"
}

// Response (409)
{
  "error": {
    "code": "RESOURCE_ALREADY_EXISTS",
    "message": "Customer with this email already exists",
    "type": "conflict_error",
    "details": {
      "existing_id": "cus_123abc",
      "field": "email",
      "value": "existing@example.com"
    },
    "request_id": "req_def456"
  }
}

{
  "event": "api.error",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "error_code": "PAYMENT_FAILED",
    "request_id": "req_xyz789",
    "customer_id": "cus_123",
    "order_id": "ord_456",
    "amount": 9999,
    "currency": "usd"
  }
}

# Trigger specific error in test mode
curl -X POST https://api.sandbox.stateset.com/v1/orders \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-Test-Error-Code: INSUFFICIENT_INVENTORY" \
  -d '{...}'