Errors

Azu provides a comprehensive error handling system with type-safe error responses, automatic error recovery, and development-friendly error pages.

Azu::Response::Error

Base class for all Azu errors.

Properties

• message : String - Error message

• status_code : Int32 - HTTP status code

• details : Hash(String, String) - Additional error details

Methods

initialize(message : String, status_code : Int32 = 500, details : Hash(String, String) = {} of String => String)

Create a new error with message, status code, and optional details.

error = Azu::Response::Error.new("User not found", 404)

to_json : String

Convert error to JSON format.

error = Azu::Response::Error.new("Invalid input", 400)
json = error.to_json
# {"error": "Invalid input", "status": 400}

Built-in Error Types

The following error classes are available in Azu::Response:

Azu::Response::BadRequest (400)

Bad Request error for invalid client requests.

raise Azu::Response::BadRequest.new("Invalid request parameters")

Azu::Response::AuthenticationError (401)

Authentication required error.

raise Azu::Response::AuthenticationError.new("Authentication required")

Azu::Response::AuthorizationError (403)

Authorization/permission error.

raise Azu::Response::AuthorizationError.new("Insufficient permissions")

Azu::Response::Forbidden (403)

Legacy alias for AuthorizationError.

raise Azu::Response::Forbidden.new  # Uses default message

Azu::Response::NotFound (404)

Resource not found error.

raise Azu::Response::NotFound.new("/users/123")  # Pass the path

Azu::Response::TimeoutError (408)

Request timeout error.

raise Azu::Response::TimeoutError.new("Request timeout")

Azu::Response::ValidationError (422)

Validation error with field-specific error messages.

# With field errors hash
raise Azu::Response::ValidationError.new({
  "email" => ["Email is invalid", "Email is required"],
  "name" => ["Name is too short"]
})

# With single field error
raise Azu::Response::ValidationError.new("email", "Email is invalid")

Azu::Response::RateLimitError (429)

Rate limit exceeded error with optional retry-after.

raise Azu::Response::RateLimitError.new(retry_after: 60)  # Retry after 60 seconds

Azu::Response::Error (500)

Base error class, defaults to 500 Internal Server Error.

raise Azu::Response::Error.new("Something went wrong")

Azu::Response::DatabaseError (500)

Database-related error.

raise Azu::Response::DatabaseError.new("Database connection failed")

Azu::Response::ExternalServiceError (502)

External service unavailable error.

raise Azu::Response::ExternalServiceError.new(service_name: "PaymentAPI", message: "Service unavailable")

Custom Error Classes

Basic Custom Error

class ValidationError < Azu::Response::Error
  def initialize(message : String, field : String)
    super(message, 422, {"field" => field})
  end
end

Error with Context

class BusinessLogicError < Azu::Response::Error
  def initialize(message : String, context : Hash(String, String))
    super(message, 400, context)
  end
end

Error with Stack Trace

class DevelopmentError < Azu::Response::Error
  def initialize(message : String, exception : Exception)
    super(message, 500, {"stack_trace" => exception.backtrace.join("\n")})
  end
end

Error Handling in Endpoints

Basic Error Handling

struct UserEndpoint
  include Azu::Endpoint

  get "/users/:id"

  def call
    user_id = request.param("id")

    begin
      user = find_user(user_id)
      response.body(user.to_json)
    rescue NotFoundError
      raise Azu::Response::NotFound.new("User not found")
    rescue ValidationError => e
      raise Azu::Response::BadRequest.new(e.message)
    end
  end
end

Error with Details

def call
  begin
    validate_input(request.body)
    process_request
  rescue ValidationError => e
    raise Azu::Response::ValidationError.new(
      e.errors.group_by(&.field).transform_values(&.map(&.message))
    )
  end
end

Error Recovery

def call
  begin
    risky_operation
  rescue NetworkError
    # Retry with exponential backoff
    retry_with_backoff
  rescue DatabaseError
    # Fallback to cached data
    use_cached_data
  end
end

Error Middleware

Automatic Error Handling

class ErrorHandler < Azu::Handler::Base
  def call(request, response)
    begin
      yield
    rescue Azu::Response::Error => e
      handle_azu_error(e, response)
    rescue Exception => e
      handle_generic_error(e, response)
    end
  end

  private def handle_azu_error(error, response)
    response.status(error.status_code)
    response.header("Content-Type", "application/json")
    response.body(error.to_json)
  end

  private def handle_generic_error(error, response)
    if Azu::Environment.development?
      response.status(500)
      response.body(error.inspect)
    else
      response.status(500)
      response.body("Internal Server Error")
    end
  end
end

Error Logging

class ErrorLogger < Azu::Handler::Base
  def call(request, response)
    begin
      yield
    rescue Exception => e
      log_error(e, request)
      raise
    end
  end

  private def log_error(error, request)
    Azu.logger.error do
      "Error: #{error.message}\n" +
      "Request: #{request.method} #{request.path}\n" +
      "Backtrace: #{error.backtrace.join("\n")}"
    end
  end
end

Error Responses

JSON Error Response

def handle_error(error, response)
  response.status(error.status_code)
  response.header("Content-Type", "application/json")
  response.body({
    "error" => error.message,
    "status" => error.status_code,
    "details" => error.details
  }.to_json)
end

HTML Error Response

def handle_error(error, response)
  response.status(error.status_code)
  response.header("Content-Type", "text/html")

  html = <<-HTML
    <!DOCTYPE html>
    <html>
      <head>
        <title>Error #{error.status_code}</title>
      </head>
      <body>
        <h1>Error #{error.status_code}</h1>
        <p>#{error.message}</p>
      </body>
    </html>
  HTML

  response.body(html)
end

Error Page Template

def handle_error(error, response)
  response.status(error.status_code)
  response.header("Content-Type", "text/html")

  template = Azu::Templates.render("error.html", {
    "error_code" => error.status_code,
    "error_message" => error.message,
    "error_details" => error.details
  })

  response.body(template)
end

Error Validation

Input Validation

class ValidationError < Azu::Response::Error
  def initialize(errors : Hash(String, Array(String)))
    super("Validation failed", 422, {"errors" => errors.to_json})
  end
end

def validate_user_input(data)
  errors = {} of String => Array(String)

  if data["name"]?.nil? || data["name"].empty?
    errors["name"] = ["Name is required"]
  end

  if data["email"]?.nil? || !valid_email?(data["email"])
    errors["email"] = ["Valid email is required"]
  end

  raise ValidationError.new(errors) unless errors.empty?
end

Business Logic Validation

def validate_business_rules(user, action)
  case action
  when "delete"
    raise Azu::Response::AuthorizationError.new("Cannot delete admin user") if user.admin?
  when "update"
    raise Azu::Response::ValidationError.new("email", "Email already exists") if email_exists?(user.email)
  end
end

Error Testing

Unit Testing

describe "Error Handling" do
  it "raises correct error for invalid input" do
    expect_raises(Azu::Response::BadRequest) do
      validate_input("invalid")
    end
  end

  it "handles custom errors correctly" do
    error = ValidationError.new("Invalid email", "email")
    expect(error.status_code).to eq(422)
    expect(error.message).to eq("Invalid email")
  end
end

Integration Testing

describe "Error Endpoints" do
  it "returns 404 for non-existent resource" do
    response = get("/users/999")
    expect(response.status).to eq(404)
    expect(response.body).to contain("User not found")
  end

  it "returns 422 for validation errors" do
    response = post("/users", {"name" => ""})
    expect(response.status).to eq(422)
    expect(response.body).to contain("Validation failed")
  end
end

Error Monitoring

Error Tracking

class ErrorTracker < Azu::Handler::Base
  def call(request, response)
    begin
      yield
    rescue Exception => e
      track_error(e, request)
      raise
    end
  end

  private def track_error(error, request)
    # Send to error tracking service
    ErrorTrackingService.track(
      error: error,
      request: request,
      timestamp: Time.utc
    )
  end
end

Error Metrics

class ErrorMetrics < Azu::Handler::Base
  def initialize
    @error_counts = {} of String => Int32
  end

  def call(request, response)
    begin
      yield
    rescue Exception => e
      increment_error_count(e.class.name)
      raise
    end
  end

  private def increment_error_count(error_type)
    @error_counts[error_type] ||= 0
    @error_counts[error_type] += 1
  end
end

Error Recovery Strategies

Retry Logic

def call_with_retry(max_attempts = 3)
  attempts = 0

  begin
    yield
  rescue TemporaryError => e
    attempts += 1
    if attempts < max_attempts
      sleep(2 ** attempts)  # Exponential backoff
      retry
    else
      raise Azu::Response::ExternalServiceError.new(message: "Service temporarily unavailable")
    end
  end
end

Fallback Responses

def call_with_fallback
  begin
    yield
  rescue DatabaseError
    # Return cached data
    response.body(cached_data.to_json)
  rescue ExternalServiceError
    # Return default response
    response.body(default_response.to_json)
  end
end

Next Steps

• Learn about Performance Optimization

• Explore Monitoring and Logging

• Understand Security Best Practices

• See Testing Strategies