Add structured error handling framework

Create custom error class hierarchy for better error handling:
- ApplicationError base class with structured logging support
- TenantErrors for multi-tenancy (TenantNotFoundError, etc.)
- ExternalServiceErrors for API integrations
- ImportExportErrors for data operations
- SubscriptionErrors for payment/billing

Add ErrorHandling controller concern that:
- Integrates with existing StructuredLogger
- Provides rescue handlers for custom errors
- Includes helper methods (log_rescued_exception, log_and_continue)

Update api_manage BaseController with structured logging for
standard rescue handlers (RecordNotFound, RecordInvalid, etc.)

Add comprehensive documentation in docs/architecture/error-handling.md
with migration guide for updating existing rescue blocks.

Co-Authored-By: Claude (claude-opus-4-5) <noreply@anthropic.com>

Author: etewiah

app/controllers/api_manage/v1/base_controller.rb

@@ -15,6 +15,7 @@ module V1
     class BaseController < ActionController::Base
       include SubdomainTenant
       include ActiveStorage::SetCurrent
+      include ErrorHandling
 
       skip_before_action :verify_authenticity_token
 
@@ -23,15 +24,18 @@ class BaseController < ActionController::Base
 
       # JSON API responses
       rescue_from ActiveRecord::RecordNotFound do |e|
-        render json: { error: 'Not found', message: e.message }, status: :not_found
+        StructuredLogger.warn("[API] Record not found", path: request.path, error: e.message)
+        render json: { success: false, error: 'Not found', message: e.message }, status: :not_found
       end
 
       rescue_from ActiveRecord::RecordInvalid do |e|
-        render json: { error: 'Validation failed', errors: e.record.errors.full_messages }, status: :unprocessable_entity
+        StructuredLogger.info("[API] Validation failed", path: request.path, errors: e.record.errors.to_hash)
+        render json: { success: false, error: 'Validation failed', errors: e.record.errors.full_messages }, status: :unprocessable_entity
       end
 
       rescue_from ActionController::ParameterMissing do |e|
-        render json: { error: 'Bad request', message: e.message }, status: :bad_request
+        StructuredLogger.warn("[API] Parameter missing", path: request.path, param: e.param.to_s)
+        render json: { success: false, error: 'Bad request', message: e.message }, status: :bad_request
       end
 
       private

app/controllers/concerns/error_handling.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+# ErrorHandling Concern
+#
+# Provides structured error logging and rescue handlers for controllers.
+# Integrates with StructuredLogger for consistent JSON logging and Sentry.
+#
+# Include in controllers that need consistent error handling.
+#
+# Usage:
+#   class MyController < ApplicationController
+#     include ErrorHandling
+#   end
+#
+# The concern provides:
+# - Structured logging via StructuredLogger (JSON format, Sentry integration)
+# - Consistent API error responses
+# - Rescue handlers for common error types
+# - Helper methods for logging caught exceptions
+#
+module ErrorHandling
+  extend ActiveSupport::Concern
+
+  included do
+    # Rescue application errors with proper logging and response
+    rescue_from ApplicationError do |error|
+      log_application_error(error)
+      render_error_response(error)
+    end
+
+    # Rescue external service errors
+    rescue_from ExternalServiceError do |error|
+      log_external_service_error(error)
+      render_error_response(error)
+    end
+
+    # Rescue tenant errors
+    rescue_from TenantNotFoundError, TenantMismatchError, TenantContextRequiredError do |error|
+      log_application_error(error, level: :warn)
+      render_error_response(error)
+    end
+
+    # Rescue subscription errors
+    rescue_from SubscriptionError, FeatureNotAvailableError do |error|
+      log_application_error(error, level: :info)
+      render_error_response(error)
+    end
+  end
+
+  private
+
+  # Log an ApplicationError with structured context
+  #
+  # @param error [ApplicationError] The error to log
+  # @param level [Symbol] Log level (:info, :warn, :error)
+  def log_application_error(error, level: :warn)
+    context = error_base_context.merge(error.respond_to?(:to_log_hash) ? error.to_log_hash : {})
+
+    case level
+    when :info
+      StructuredLogger.info("[#{error.class.name}] #{error.message}", **context)
+    when :warn
+      StructuredLogger.warn("[#{error.class.name}] #{error.message}", **context)
+    else
+      StructuredLogger.error("[#{error.class.name}] #{error.message}", **context)
+    end
+  end
+
+  # Log an external service error with full context
+  #
+  # @param error [ExternalServiceError] The error to log
+  def log_external_service_error(error)
+    context = error_base_context.merge(
+      service_name: error.service_name,
+      original_error: error.original_error&.message
+    ).compact
+
+    StructuredLogger.error("[ExternalService] #{error.message}", **context)
+  end
+
+  # Log a rescued exception with full context
+  # Use this in rescue blocks for proper error tracking
+  #
+  # @param error [Exception] The rescued exception
+  # @param context_message [String] Description of what was being attempted
+  # @param extra_context [Hash] Additional context to include
+  #
+  # @example
+  #   begin
+  #     process_payment
+  #   rescue Stripe::CardError => e
+  #     log_rescued_exception(e, context_message: "Processing payment", order_id: order.id)
+  #     # handle gracefully...
+  #   end
+  def log_rescued_exception(error, context_message: nil, **extra_context)
+    context = error_base_context.merge(extra_context)
+    message = context_message || "Rescued exception"
+
+    StructuredLogger.exception(error, "[#{controller_name}##{action_name}] #{message}", **context)
+  end
+
+  # Log an error without raising (for graceful degradation)
+  # Use when you want to catch an error, log it, but continue execution
+  #
+  # @param error [Exception] The error that occurred
+  # @param fallback_value [Object] What to return instead
+  # @param context_message [String] What was being attempted
+  #
+  # @example
+  #   def fetch_optional_data
+  #     SomeService.call
+  #   rescue SomeError => e
+  #     log_and_continue(e, fallback_value: [], context_message: "Fetching optional data")
+  #   end
+  def log_and_continue(error, fallback_value: nil, context_message: nil, **extra_context)
+    log_rescued_exception(error, context_message: context_message, **extra_context)
+    fallback_value
+  end
+
+  # Base context included in all error logs
+  def error_base_context
+    {
+      controller: controller_name,
+      action: action_name,
+      path: request.path,
+      method: request.method,
+      user_id: respond_to?(:current_user, true) ? current_user&.id : nil,
+      website_id: respond_to?(:current_website, true) ? current_website&.id : nil
+    }.compact
+  end
+
+  # Render a JSON error response for ApplicationError subclasses
+  def render_error_response(error)
+    status = error.respond_to?(:http_status) ? error.http_status : :internal_server_error
+
+    if request.format.json? || request.content_type&.include?('json')
+      render json: error_to_json(error), status: status
+    else
+      # For HTML requests, set flash and redirect or render error page
+      flash[:error] = error.message
+      if request.referer.present?
+        redirect_back(fallback_location: root_path)
+      else
+        render plain: error.message, status: status
+      end
+    end
+  end
+
+  # Convert error to JSON response format
+  def error_to_json(error)
+    response = { success: false }
+
+    if error.respond_to?(:to_api_response)
+      response.merge(error.to_api_response)
+    else
+      response.merge(
+        error: error.class.name.demodulize.underscore.upcase,
+        message: error.message
+      )
+    end
+  end
+end

app/errors/application_error.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Base error class for all application-specific errors
+#
+# Provides structured error information for logging and API responses.
+# All domain-specific errors should inherit from this class.
+#
+# Usage:
+#   raise ApplicationError.new("Something went wrong", code: "GENERIC_ERROR")
+#   raise TenantNotFoundError.new("Website not found")
+#
+# Logging:
+#   rescue ApplicationError => e
+#     Rails.logger.error(e.to_log_hash)
+#
+class ApplicationError < StandardError
+  attr_reader :code, :details, :http_status
+
+  # @param message [String] Human-readable error message
+  # @param code [String, nil] Machine-readable error code (defaults to class name)
+  # @param details [Hash] Additional context for debugging
+  # @param http_status [Symbol] HTTP status code for API responses (default: :internal_server_error)
+  def initialize(message = nil, code: nil, details: {}, http_status: :internal_server_error)
+    @code = code || self.class.name.demodulize.underscore.upcase
+    @details = details
+    @http_status = http_status
+    super(message || default_message)
+  end
+
+  # Returns a hash suitable for structured logging
+  # @return [Hash]
+  def to_log_hash
+    {
+      error_class: self.class.name,
+      error_code: code,
+      message: message,
+      details: details.presence
+    }.compact
+  end
+
+  # Returns a hash suitable for JSON API responses
+  # @return [Hash]
+  def to_api_response
+    {
+      error: code,
+      message: message,
+      details: details.presence
+    }.compact
+  end
+
+  private
+
+  def default_message
+    "An error occurred"
+  end
+end

app/errors/external_service_errors.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# External service related errors
+#
+# These errors are raised when external API calls fail.
+#
+
+# Base class for external service errors
+class ExternalServiceError < ApplicationError
+  attr_reader :service_name, :original_error
+
+  def initialize(message = nil, service_name: nil, original_error: nil, details: {})
+    @service_name = service_name
+    @original_error = original_error
+
+    details[:service] = service_name if service_name
+    details[:original_error] = original_error&.message if original_error
+
+    super(
+      message || "External service error",
+      code: "EXTERNAL_SERVICE_ERROR",
+      details: details,
+      http_status: :bad_gateway
+    )
+  end
+
+  def to_log_hash
+    super.merge(
+      service_name: service_name,
+      original_error_class: original_error&.class&.name,
+      original_error_message: original_error&.message
+    ).compact
+  end
+end
+
+# Raised when an external API times out
+class ExternalServiceTimeoutError < ExternalServiceError
+  def initialize(message = nil, service_name: nil, timeout_seconds: nil, details: {})
+    details[:timeout_seconds] = timeout_seconds if timeout_seconds
+    super(
+      message || "External service request timed out",
+      service_name: service_name,
+      details: details
+    )
+    @code = "EXTERNAL_SERVICE_TIMEOUT"
+    @http_status = :gateway_timeout
+  end
+end
+
+# Raised when an external API returns an error response
+class ExternalServiceApiError < ExternalServiceError
+  attr_reader :status_code, :response_body
+
+  def initialize(message = nil, service_name: nil, status_code: nil, response_body: nil, details: {})
+    @status_code = status_code
+    @response_body = response_body
+
+    details[:status_code] = status_code if status_code
+    details[:response_body] = truncate_response(response_body) if response_body
+
+    super(
+      message || "External service returned an error",
+      service_name: service_name,
+      details: details
+    )
+    @code = "EXTERNAL_SERVICE_API_ERROR"
+  end
+
+  private
+
+  def truncate_response(body)
+    return body if body.nil? || body.length <= 500
+    "#{body[0..500]}... (truncated)"
+  end
+end
+
+# Raised when an external service rate limits our requests
+class ExternalServiceRateLimitError < ExternalServiceError
+  attr_reader :retry_after
+
+  def initialize(message = nil, service_name: nil, retry_after: nil, details: {})
+    @retry_after = retry_after
+    details[:retry_after] = retry_after if retry_after
+
+    super(
+      message || "External service rate limit exceeded",
+      service_name: service_name,
+      details: details
+    )
+    @code = "EXTERNAL_SERVICE_RATE_LIMITED"
+    @http_status = :too_many_requests
+  end
+end
+
+# Raised when external service credentials are missing or invalid
+class ExternalServiceConfigurationError < ExternalServiceError
+  def initialize(message = nil, service_name: nil, missing_config: nil, details: {})
+    details[:missing_config] = missing_config if missing_config
+
+    super(
+      message || "External service not configured",
+      service_name: service_name,
+      details: details
+    )
+    @code = "EXTERNAL_SERVICE_NOT_CONFIGURED"
+    @http_status = :service_unavailable
+  end
+end