{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "additional": "context-specific details"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "Article creation currently requires admin API key"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "errors": [
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "number",
          "path": ["title"],
          "message": "Expected string, received number"
        }
      ]
    }
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  }
}

const response = await fetch('/api/v1/articles', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error.error.message);
  return;
}

const data = await response.json();

async function handleApiError(response) {
  const error = await response.json();
  
  switch (error.error.code) {
    case 'AUTHENTICATION_ERROR':
    case 'INVALID_API_KEY':
      // Redirect to login or refresh API key
      redirectToAuth();
      break;
      
    case 'AUTHORIZATION_ERROR':
      // Show permission denied message
      showError('You don\'t have permission for this action');
      break;
      
    case 'VALIDATION_ERROR':
      // Display field-specific errors
      showValidationErrors(error.error.details.errors);
      break;
      
    case 'RATE_LIMIT_EXCEEDED':
      // Implement exponential backoff
      await retryAfterDelay();
      break;
      
    default:
      // Generic error handling
      showError('Something went wrong. Please try again.');
  }
}

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited - wait before retry
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      if (response.status >= 500) {
        // Server error - retry
        if (attempt === maxRetries) throw new Error('Server error after retries');
        continue;
      }
      
      return response;
      
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

function validateArticleData(article) {
  const errors = [];
  
  if (!article.title || article.title.length > 500) {
    errors.push('Title is required and must be 500 characters or less');
  }
  
  if (!article.content) {
    errors.push('Content is required');
  }
  
  if (article.tags && article.tags.length > 20) {
    errors.push('Maximum 20 tags allowed');
  }
  
  return errors;
}

// Use before API call
const validationErrors = validateArticleData(articleData);
if (validationErrors.length > 0) {
  showErrors(validationErrors);
  return;
}

// Log all API requests and responses
const originalFetch = fetch;
window.fetch = async (...args) => {
  console.log('API Request:', args);
  const response = await originalFetch(...args);
  const clonedResponse = response.clone();
  const body = await clonedResponse.json();
  console.log('API Response:', response.status, body);
  return response;
};