Laravel Json Aware Exception Handler

1.1.8 2018-05-31 09:26 UTC

This package is auto-updated.

Last update: 2020-11-29 06:18:36 UTC


Latest Version on Packagist Software License Total Downloads Build Status

Laravel Json Aware Exception Handler

Every one likes cool error message pages. Github has an awesome 404.

And it's very easy to create your own custom error pages for html responses.

But doing this for Ajax and Json responses meant either doing something generic or figuring out your own solution. Often something like returning an error message like 'Sorry we cant handle your request'. Nothing informative.

This package solves this problem.

Once it's installed. Tune your error messages for over a dozen possible error codes. You can even add more. Just create a ZizzZazzException assign a status code to it, and a custom message. Done!


Install Laravel Json Aware Exception Handler with Composer.

$ composer require robrogers3/laravel-json-aware-exception-handler



Using it:

Option 1: Update your .env file by adding this line:


This will use the JsonHandler for json requests and the Laravel Exception Handler for regular requests.

Note: it will completely ignore your app's Exception Handler. This means you can't override anything in this class.

Option 2: Update your App Handler class to extend the JsonAwareExceptionHandler

You do not have to update your .env file.

The benefit of this is you can overide how the JsonAwareExceptionHandler

To do this you need to change your App\Exceptions\Handler class to extend RobRogers3\LaravelExceptionHandler\JsonAwareExceptionHandler rather than extending Illuminate\Foundation\Exceptions\Handler. Like so:


use RobRogers3\LaravelExceptionHandler\JsonAwareExceptionHandler;

class Handler extends JsonAwareExceptionHandler

Last Step

You need to run this artisan command:

$ artisan vendor:publish

This will copy the exception messages to your local lang directory.

Optional Setup.

Open the exceptionmessages.php and change the messages you want to show for different http status codes.

You may want to change 401 to something more clever or more corporate. It's up to you.


Server Side Usage

There really is only one thing to use: Taking advantage of the MessagingException::class

Throwing this with a custom message allows you to display something detailed or specific to the situtation.

Client Side Usage with Ajax

Here's where you want to take advantage of this.

Take a look at this handling of an ajax response error.

	handle (error) {
	    if ( {
	    //the error message returned by the json response corresponds to the property

	    //Usually it's a string
		 if (typeof == 'string') {
		     return alert(;

		 //validation errors are an array
		 if (error.response.status == 422 && {
		     let errors = []; => {
		     return alert(errors.join("\n"));

		 //used to handle a teapot message 418
		 //can be a random exception you throw as say MessagingException
		 //you can tweek your teapot messages to have an extra 'message' property. Up to you.
		 //by default it doesn't 
		 if (error.response.status == 418 && {
		     return alert(;
	     return alert('We could not handle your request');