❗ Custom Error Types

Securial defines custom error classes to handle various failure scenarios gracefully. These custom errors help you detect misconfigurations, authentication issues, or session problems with more clarity.

---

🛠️ Configuration Errors

📍 Defined in: lib/securial/config/errors.rb

These errors are raised when invalid or missing configurations are detected in the securial.rb initializer.

Errors are in the namespace Securial::Config::Errors

Error Class	Description
ConfigAdminRoleError	Raised if the admin_role configuration is missing or invalid
ConfigSessionExpirationDurationError	Raised if session_expiration_duration is not defined properly
ConfigSessionAlgorithmError	Raised when an unsupported or missing session_algorithm is provided
ConfigSessionSecretError	Raised if session_secret is not defined or is insecure
ConfigMailerSenderError	Raised if mailer_sender is not a valid email or is missing
ConfigPasswordError	Raised for issues related to password length, complexity, or missing values
ConfigTimestampsInResponseError	Raised if timestamps_in_response is nil or invalid

🔍 Tip: These errors often occur at boot time or when initializing Securial. Check your initializer file if you encounter one.

---

🔐 Session Errors

📍 Defined in: lib/securial/sessions/errors.rb

These errors are raised during session validation and token handling.

Errors are in the namespace Securial::Sessions::Errors

Error Class	Description
SessionRevokedError	Raised when a session token has been explicitly revoked
SessionExpiredError	Raised when the session token has expired based on configured duration

🧠 Note:
Each of these errors includes human-readable messages and symbolic error codes to support structured error handling in your controllers or API responses.

---

🔧 Validation errors

When invalid data is submitted (e.g., short passwords or malformed emails), Securial returns a 422 Unprocessable Entity with an errors array. Each entry includes a field and a human‑readable message. Admin endpoints also include an instructions field to guide clients on how to fix the issue.

🔒 Permission errors

Calling admin endpoints without the appropriate role triggers a Forbidden response. Use authenticate_admin! to guard actions that only admins should perform.

---

🧪 Handling Errors in Your Application

To gracefully handle Securial-specific errors, you can rescue from them in your controllers or globally in ApplicationController:

rescue_from Securial::Config::Errors::ConfigAdminRoleError, with: :handle_config_error

def handle_config_error(error)
  render json: { error: error.message }, status: :internal_server_error
end

For a full list of error classes and their details, refer to the source files under lib/securial.