module ApiErrorHandler
extend ActiveSupport::Concern
included do
rescue_from StandardError, with: :handle_standard_error
rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
rescue_from ActiveRecord::RecordInvalid, with: :handle_validation_error
rescue_from Api::UnauthorizedError, with: :handle_unauthorized
end
private
def handle_standard_error(exception)
Rails.logger.error("#{exception.class}: #{exception.message}\n#{exception.backtrace.join("\n")}")
render json: {
error: 'INTERNAL_SERVER_ERROR',
message: 'An unexpected error occurred',
request_id: request.request_id
}, status: :internal_server_error
end
def handle_not_found(exception)
render json: {
error: 'NOT_FOUND',
message: exception.message,
request_id: request.request_id
}, status: :not_found
end
def handle_validation_error(exception)
render json: {
error: 'VALIDATION_ERROR',
message: 'Validation failed',
details: exception.record.errors.as_json,
request_id: request.request_id
}, status: :unprocessable_entity
end
def handle_unauthorized(exception)
render json: {
error: 'UNAUTHORIZED',
message: exception.message,
request_id: request.request_id
}, status: :unauthorized
end
end
Consistent error handling transforms debugging from guesswork into systematic troubleshooting. I use a rescue handler that catches exceptions globally and transforms them into a standard JSON structure containing an error code, human-readable message, and optional details hash for validation failures. This pattern ensures every API response follows the same contract regardless of which layer raised the exception. I also include a request_id in error responses so clients can reference specific failures when reporting issues. For production systems, I log the full exception with backtrace server-side while returning sanitized messages to clients to avoid leaking implementation details. Custom exception classes like Api::UnauthorizedError map to specific HTTP status codes.
