Error Handling

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "type": "client_error",
    "timestamp": "2024-01-20T15:30:00Z",
    "requestId": "req_abc123def456",
    "details": {
      "field": "email",
      "value": "invalid-email",
      "constraint": "Valid email format required"
    }
  },
  "meta": {
    "documentation": "https://docs.megavault.com/api/errors#ERROR_CODE",
    "support": "https://support.megavault.com"
  }
}

// Invalid credentials
{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password",
    "type": "authentication_error"
  }
}

// Token expired
{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Authentication token has expired",
    "type": "authentication_error",
    "details": {
      "expiredAt": "2024-01-20T14:30:00Z",
      "refreshRequired": true
    }
  }
}

// Account suspended
{
  "success": false,
  "error": {
    "code": "ACCOUNT_SUSPENDED",
    "message": "Account has been suspended due to policy violation",
    "type": "authentication_error",
    "details": {
      "reason": "terms_violation",
      "suspendedAt": "2024-01-15T10:00:00Z",
      "appealUrl": "https://support.megavault.com/appeal"
    }
  }
}

// File not found
{
  "success": false,
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "The requested file could not be found",
    "type": "client_error",
    "details": {
      "fileId": "file_123456789",
      "possibleCauses": ["File was deleted", "Invalid file ID", "Access denied"]
    }
  }
}

// Storage quota exceeded
{
  "success": false,
  "error": {
    "code": "STORAGE_QUOTA_EXCEEDED",
    "message": "Upload would exceed your storage quota",
    "type": "client_error",
    "details": {
      "currentUsage": 5368709120,
      "storageLimit": 5368709120,
      "fileSize": 1048576,
      "upgradeUrl": "https://megavault.com/upgrade"
    }
  }
}

// Unsupported file type
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILE_TYPE",
    "message": "File type not supported",
    "type": "client_error",
    "details": {
      "fileType": "exe",
      "supportedTypes": ["jpg", "png", "pdf", "docx", "txt"]
    }
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "type": "client_error",
    "details": {
      "fields": [
        {
          "field": "email",
          "value": "invalid-email",
          "errors": [
            {
              "code": "INVALID_FORMAT",
              "message": "Must be a valid email address"
            }
          ]
        },
        {
          "field": "password",
          "value": "[REDACTED]",
          "errors": [
            {
              "code": "TOO_SHORT",
              "message": "Password must be at least 8 characters long"
            },
            {
              "code": "MISSING_UPPERCASE",
              "message": "Password must contain at least one uppercase letter"
            }
          ]
        }
      ]
    }
  }
}

class MegaVaultAPIError extends Error {
  constructor(response, requestId) {
    super(response.error.message);
    this.name = 'MegaVaultAPIError';
    this.code = response.error.code;
    this.type = response.error.type;
    this.details = response.error.details;
    this.requestId = requestId;
    this.statusCode = response.status;
  }
}

async function apiCall(endpoint, options = {}) {
  try {
    const response = await fetch(endpoint, options);
    const data = await response.json();
    
    if (!response.ok || !data.success) {
      throw new MegaVaultAPIError(data, response.headers.get('X-Request-ID'));
    }
    
    return data;
  } catch (error) {
    if (error instanceof MegaVaultAPIError) {
      handleAPIError(error);
    } else {
      handleNetworkError(error);
    }
    throw error;
  }
}

function handleAPIError(error) {
  switch (error.code) {
    case 'TOKEN_EXPIRED':
      // Refresh token and retry
      return refreshTokenAndRetry();
    
    case 'STORAGE_QUOTA_EXCEEDED':
      // Show upgrade prompt
      showUpgradeDialog(error.details.upgradeUrl);
      break;
    
    case 'VALIDATION_ERROR':
      // Show field-specific errors
      displayValidationErrors(error.details.fields);
      break;
    
    case 'RATE_LIMIT_EXCEEDED':
      // Implement exponential backoff
      const retryAfter = error.details.retryAfter || 60;
      scheduleRetry(retryAfter);
      break;
    
    default:
      // Generic error handling
      showErrorMessage(error.message);
  }
}

async function retryableRequest(endpoint, options, maxRetries = 3) {
  let lastError;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall(endpoint, options);
    } catch (error) {
      lastError = error;
      
      // Don't retry client errors (4xx) except 429
      if (error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
        throw error;
      }
      
      // Calculate exponential backoff delay
      const delay = Math.min(1000 * Math.pow(2, attempt - 1), 30000);
      
      if (attempt < maxRetries) {
        console.log(`Request failed, retrying in ${delay}ms (attempt ${attempt}/${maxRetries})`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }
  
  throw lastError;
}

function handleRateLimit(error) {
  const retryAfter = error.details.retryAfter || 60;
  const resetTime = new Date(Date.now() + retryAfter * 1000);
  
  console.log(`Rate limited. Retry after: ${resetTime.toISOString()}`);
  
  // Show user-friendly message
  showToast(`Too many requests. Please wait ${retryAfter} seconds.`);
  
  // Schedule retry
  setTimeout(() => {
    // Retry the failed request
    retryFailedRequest();
  }, retryAfter * 1000);
}