Laravel Exception Response

Drop-in JSON exception responses for Laravel 11, 12, and 13 APIs — built for the slim application skeleton (no app/Exceptions/Handler.php).

• ✅ Uniform JSON shape for every exception
• ✅ Translatable messages (English + Spanish included; bring your own locales)
• ✅ Stable machine-readable error_code for clients
• ✅ Debug-mode trace info gated by app.debug
• ✅ ExceptionRendered event for logging / Sentry tagging
• ✅ Web routes untouched

Requirements

• PHP 8.2+
• Laravel 11.x, 12.x, or 13.x

Installation

composer require anilkumarthakur/laravel-exception-response

The service provider is auto-discovered.

Usage

Register the renderers inside bootstrap/app.php:

use AnilKumarThakur\ExceptionResponse\JsonExceptions;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        //
    })
    ->withExceptions(function (Exceptions $exceptions) {
        JsonExceptions::register($exceptions);
    })
    ->create();

Any request matching api/* or sending Accept: application/json will get a uniform JSON payload:

{
  "message": "Resource not found.",
  "error_code": "not_found"
}

Web routes still render the standard Laravel error pages.

Response shape

| Field | Always present | Notes | | --- | --- | --- | | message | yes | Localized; uses the exception's own message when set, otherwise the translated default | | error_code | when include_error_code (default true) | Stable string like unauthenticated, validation_failed | | errors | only on ValidationException | Field-level validation errors | | exception | when include_exception_class is true | FQCN of the thrown exception | | file, line, trace | when app.debug and include_trace_in_debug are both true | trace is truncated to trace_depth frames |

Handled exceptions

| Exception | Status | error_code | | --- | --- | --- | | ValidationException | 422 | validation_failed (with errors) | | AuthenticationException | 401 | unauthenticated | | AuthorizationException | 403 | unauthorized | | ModelNotFoundException | 404 | model_not_found | | NotFoundHttpException | 404 | not_found | | MethodNotAllowedHttpException | 405 | method_not_allowed | | ThrottleRequestsException | 429 | too_many_requests | | TokenMismatchException | 419 | csrf_token_mismatch | | PostTooLargeException | 413 | payload_too_large | | QueryException | 500 | query_error | | BadMethodCallException | 500 | bad_method | | InvalidArgumentException | 400 | invalid_argument | | BindingResolutionException | 500 | binding_resolution | | Any HttpExceptionInterface | exception's status | mapped from status when known |

Configuration

Publish the config:

php artisan vendor:publish --tag=exception-response-config

config/exception-response.php:

return [
    'api_prefixes'             => ['api/*'],
    'include_exception_class'  => false,
    'include_trace_in_debug'   => true,
    'trace_depth'              => 10,
    'include_error_code'       => true,
];

Translations

Default messages live under lang/{locale}/messages.php. English and Spanish ship out of the box. Switch locale anywhere in your app (App::setLocale('es')) and responses follow.

Publish the lang files to override or add languages:

php artisan vendor:publish --tag=exception-response-lang

The translation keys (also used as error_code values):

unauthenticated, unauthorized, model_not_found, not_found, method_not_allowed,
too_many_requests, csrf_token_mismatch, payload_too_large, query_error,
bad_method, invalid_argument, binding_resolution, validation_failed, server_error

When the thrown exception has a custom message (e.g. abort(404, 'No such record.') or throw new AuthenticationException('Token expired.')), that message wins. Translations are used only when the exception carries the framework's default message or no message at all.

Events

Every JSON response dispatches AnilKumarThakur\ExceptionResponse\Events\ExceptionRendered:

use AnilKumarThakur\ExceptionResponse\Events\ExceptionRendered;
use Illuminate\Support\Facades\Event;

Event::listen(function (ExceptionRendered $event) {
    logger()->warning('API error', [
        'status'    => $event->response->getStatusCode(),
        'exception' => $event->exception::class,
        'path'      => $event->request->path(),
    ]);
});

Useful for Sentry / Bugsnag tagging, request-id correlation, or per-tenant alerting.

Extending

Register your own renderer alongside this one. Add it inside withExceptions() after JsonExceptions::register() — first-registered wins for matching exception types, so put the more specific callback first:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (\App\Exceptions\PaymentFailed $e) {
        return response()->json([
            'message'    => $e->getMessage(),
            'error_code' => 'payment_failed',
        ], 402);
    });

    JsonExceptions::register($exceptions);
})

Development

composer install
composer test         # PHPUnit
composer analyse      # PHPStan level 10
composer format       # Pint (apply)
composer format:check # Pint (verify)
composer qa           # everything above

Architecture

src/
├── JsonExceptions.php                # public static API entry point
├── Renderer.php                      # registers per-exception render callbacks
├── ExceptionResponseServiceProvider.php
├── Events/
│   └── ExceptionRendered.php         # dispatched after every JSON response
└── Support/
    ├── RequestMatcher.php            # decides if a request wants JSON
    └── Payload.php                   # builds the response body
config/
└── exception-response.php
lang/
├── en/messages.php
└── es/messages.php
tests/
├── TestCase.php
├── Feature/
└── Unit/

Versioning, security, contributions

• Follows Semantic Versioning. Breaking changes ship as a major version with notes in UPGRADE.md.
• Security issues: see SECURITY.md. Please do not file public issues for vulnerabilities.
• Contributions welcome — see CONTRIBUTING.md.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.md.