Error Handling Best Practices

Exception Reporting and Rendering

There are two valid approaches — choose one and apply it consistently across the project.

Co-location on the exception class — keeps behavior alongside the exception definition, easier to find:

class InvalidOrderException extends Exception
{
    public function report(): void { /* custom reporting */ }

    public function render(Request $request): Response
    {
        return response()->view('errors.invalid-order', status: 422);
    }
}

Centralized in bootstrap/app.php — all exception handling in one place, easier to see the full picture:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (InvalidOrderException $e) { /* ... */ });
    $exceptions->render(function (InvalidOrderException $e, Request $request) {
        return response()->view('errors.invalid-order', status: 422);
    });
})

Check the existing codebase and follow whichever pattern is already established.

Use `ShouldntReport` for Exceptions That Should Never Log

More discoverable than listing classes in dontReport().

class PodcastProcessingException extends Exception implements ShouldntReport {}

Throttle High-Volume Exceptions

A single failing integration can flood error tracking. Use throttle() to rate-limit per exception type.

Enable `dontReportDuplicates()`

Prevents the same exception instance from being logged multiple times when report($e) is called in multiple catch blocks.

Force JSON Error Rendering for API Routes

Laravel auto-detects Accept: application/json but API clients may not set it. Explicitly declare JSON rendering for API routes.

$exceptions->shouldRenderJsonWhen(function (Request $request, Throwable $e) {
    return $request->is('api/*') || $request->expectsJson();
});

Add Context to Exception Classes

Attach structured data to exceptions at the source via a context() method — Laravel includes it automatically in the log entry.

class InvalidOrderException extends Exception
{
    public function context(): array
    {
        return ['order_id' => $this->orderId];
    }
}

2.2 KiB Raw Blame History