Error Handling

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid or cannot be served.",
    "details": {
      "field": "start_time",
      "reason": "Must be a future date"
    }
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "The request contains invalid data.",
    "details": {
      "errors": [
        {
          "field": "customer.email",
          "message": "Must be a valid email address"
        },
        {
          "field": "start_time",
          "message": "Must be in the future"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "appointment_not_found",
    "message": "No appointment found with ID apt_abc123."
  }
}

{
  "error": {
    "code": "slot_unavailable",
    "message": "The requested time slot is no longer available.",
    "details": {
      "requested_time": "2025-01-15T10:00:00Z",
      "next_available": "2025-01-15T11:00:00Z"
    }
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "limit": 60,
      "period": "minute",
      "retry_after": 45
    }
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again.",
    "details": {
      "request_id": "req_xyz789"
    }
  }
}

try {
  const response = await fetch('https://api.bookwell.app/v1/appointments', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(appointmentData)
  });
 
  if (!response.ok) {
    const error = await response.json();
    handleError(response.status, error);
    return;
  }
 
  const data = await response.json();
  // Process successful response
} catch (networkError) {
  // Handle network errors
}

function handleError(status, error) {
  switch (error.error.code) {
    case 'slot_unavailable':
      // Show alternative times
      showAlternativeSlots(error.error.details.next_available);
      break;
 
    case 'validation_error':
      // Show field errors
      showFieldErrors(error.error.details.errors);
      break;
 
    case 'rate_limit_exceeded':
      // Wait and retry
      const retryAfter = error.error.details.retry_after;
      setTimeout(() => retryRequest(), retryAfter * 1000);
      break;
 
    case 'authentication_required':
    case 'invalid_api_key':
      // Handle auth issues
      refreshAuthentication();
      break;
 
    default:
      // Generic error handling
      showGenericError(error.error.message);
  }
}

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      if (!isRetryable(error)) throw error;
 
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await sleep(delay);
    }
  }
}

const userMessages = {
  'slot_unavailable': 'This time is no longer available. Please choose another.',
  'customer_blocked': 'Unable to complete booking. Please contact us.',
  'rate_limit_exceeded': 'Too many requests. Please wait a moment.',
  // ...
};
 
function getUserMessage(code) {
  return userMessages[code] || 'Something went wrong. Please try again.';
}

function logError(error, context) {
  console.error('API Error:', {
    code: error.error.code,
    message: error.error.message,
    details: error.error.details,
    context: context,
    timestamp: new Date().toISOString()
  });
}

function validateAppointmentData(data) {
  const errors = [];
 
  if (!data.service_id) {
    errors.push({ field: 'service_id', message: 'Service is required' });
  }
 
  if (!data.start_time || new Date(data.start_time) <= new Date()) {
    errors.push({ field: 'start_time', message: 'Must be a future time' });
  }
 
  if (!data.customer?.email?.includes('@')) {
    errors.push({ field: 'customer.email', message: 'Valid email required' });
  }
 
  return errors;
}