Error Handling & Custom Exceptions
Relevant source files
The following files were used as context for generating this wiki page:
The QashierWise application employs a two-pronged approach to error handling, combining specific backend custom exceptions for predictable business logic failures with a robust frontend system for displaying these errors to the user. This strategy ensures that API failures are managed gracefully, providing clear, contextual feedback through global toast notifications and in-component error messages.
This document outlines the custom exceptions defined in the backend and details how the frontend, primarily using Alpine.js, consumes and presents these errors.
Backend Error Handling
The backend utilizes two main strategies for handling errors: custom exception classes for critical, flow-breaking issues, and structured validation responses for input errors.
Custom Exception Classes
For specific, high-level failures related to WhatsApp integration, the application defines several custom exception classes. These exceptions are designed to be caught by Laravel's exception handler and rendered as a standardized JSON response, which the frontend can easily parse.
The primary custom exceptions are:
| Exception Class | Purpose | HTTP Status | Default Message |
|---|---|---|---|
WhatsAppNotConnectedException | Thrown when an action requires an active WhatsApp account, but none is connected for the user. | 409 Conflict | "WhatsApp account is not connected." |
WhatsAppTokenExpiredException | Thrown when the user's WhatsApp access token has expired, requiring re-authentication. | 401 Unauthorized | "WhatsApp token has expired. Please reconnect your account." |
EmbeddedSignupDisabledException | Thrown if a user attempts to access the Facebook Embedded Signup flow when it's disabled in the application configuration. | 403 Forbidden | "Embedded signup is disabled." |
Sources: app/Exceptions/WhatsAppNotConnectedException.php, app/Exceptions/WhatsAppTokenExpiredException.php, app/Exceptions/EmbeddedSignupDisabledException.php
Each of these classes extends PHP's base Exception class and implements a render method. This method is responsible for creating a JsonResponse with a specific HTTP status code and a consistent error message format.
The diagram below shows the inheritance structure of these custom exceptions.
Service-Layer Validation
In addition to exceptions, the application uses service-layer validation to handle input errors before they result in an exception or an API call failure. The TemplateService, for example, contains numerous validation methods.
validateTemplateName(string $name): arrayvalidateFooter(?string $footer): arrayvalidateBody(string $body): arrayvalidateButtons(?array $buttons): arrayvalidateRequiredFields(array $data): array
These methods do not throw exceptions. Instead, they return an array containing a valid boolean and an error message string. The main service methods, like createTemplate, orchestrate these validation checks and return a structured error response if any check fails. This prevents invalid data from ever reaching the external Meta API.
Sources: app/Services/TemplateService.php:45-231
The following flowchart illustrates the validation flow within the createTemplate method of the TemplateService.
Frontend Error Display
The frontend is designed to gracefully handle API errors by providing immediate and clear feedback to the user. This is primarily managed within Alpine.js components in the Blade templates.
Toast Notifications
A global toast notification system is implemented to provide non-blocking feedback for various actions.
- Manager: A
toastManager()Alpine.js component is defined inresources/views/dashboard/templates.blade.php. It manages an array oftoastsand handles their display and dismissal. - Types: Supports
success,error,warning, andinfotypes, each with distinct styling. - Global Access: A global
window.showToast()function is exposed, allowing any JavaScript component to easily trigger a notification.
This system is used for general feedback, such as when syncing templates from Meta or when a connection error occurs.
Sources: resources/views/dashboard/templates.blade.php:5-45, 1421-1463
Modal-Specific API Errors
For operations within modals (e.g., creating, editing, or deleting a template), errors are displayed directly within the modal to provide context and allow the user to correct issues without losing their work.
The templatesManager Alpine.js component in templates.blade.php uses dedicated state variables for this purpose:
apiError: For the "Create Template" modal.editApiError: For the "Edit Template" modal.deleteApiError: For the "Delete Template" modal.
When an API call fails, the catch block of the fetch request or a check for !data.success populates the relevant error variable. The modal's HTML contains a corresponding x-show directive to render an error banner when this variable is not null.
<!-- API Error Display in Create Modal -->
<div x-show="apiError" x-transition class="mb-4 p-3 bg-red-50 border border-red-200 rounded-lg">
<div class="flex items-start gap-2">
<i class="fas fa-exclamation-circle text-red-500 mt-0.5"></i>
<div class="flex-1">
<p class="text-sm font-medium text-red-800">API Error</p>
<p class="text-sm text-red-600" x-text="apiError"></p>
</div>
<button @click="apiError = null" class="text-red-400 hover:text-red-600 ...">
<i class="fas fa-times"></i>
</button>
</div>
</div>
Sources: resources/views/dashboard/templates.blade.php:1003-1015
The JavaScript logic to set this state is as follows:
// From submitCreate() method
// ...
} else {
// Extract error message from API response
const errorMsg = data.message || data.error || 'Failed to create template';
this.apiError = errorMsg;
this.showToast(errorMsg, 'error');
}
// ...
Sources: resources/views/dashboard/templates.blade.php:1710-1714
API Error Handling Flow
The sequence diagram below illustrates a complete error handling flow, from a user action to the final display of an error message on the frontend.
A similar pattern is used for handling errors during the WhatsApp account connection process, where errors from the Facebook SDK or the backend callback are caught and displayed as toast notifications.
Sources: resources/views/dashboard/whatsapp-account.blade.php:470-474, 532-536
Summary
The project's error handling is designed to be robust and user-friendly. On the backend, custom exceptions and service-layer validations produce clear, structured error responses for predictable failures. On the frontend, a flexible system of toast notifications and modal-specific error displays consumes these responses, providing users with immediate and contextual feedback. This layered approach enhances the user experience, simplifies debugging, and ensures application stability.