API Exceptions for Laravel

All in one solution for exception for JSON REST APIs on Laravel and Lumen.


The goal of this package is to provide you with a set of most common exceptions that may be needed while developing JSON REST API. It also:

  • Handles exceptions output.
  • Handles exceptions report to logs.
  • Overwrites default Validator to make validation errors more verbose.
  • Has a FormRequest that to handle validation errors and pass them to ApiExceptions layer.
  • Has middleware to catch all system errors such us RuntimeExceptions or ModelNotFoundException to handle them and threat as normal ApiExceptions.


PHP 5.4+ or HHVM 3.3+, Composer and Laravel 5.1+ are required.

To get the latest version of Laravel Laravel-API-Debugger, simply add the following line to the require block of your composer.json file.

"lanin/laravel-api-exceptions": "^0.1.0"

You’ll then need to run composer install or composer update to download it and have the autoloader updated.

Once Laravel-API-Exceptions is installed, you need to register the service provider. Open up config/app.php and add the following to the providers key.



Every ApiException can be thrown as a normal exception and they will be automatically serialized to JSON with corresponding HTTP status:

    "id": "not_found",
    "message": "Requested object not found."

This object will be also populated with trace info, when APP_DEBUG is true.

Also it can have meta attribute when there is additional info. For example for validation errors:

	"id": "validation_failed",
	"message": "Validation failed.",
	"meta": {
		"errors": {
			"tags": [{
				"rule": "max.array",
				"message": "The tags may not have more than 10 items.",
				"parameters": ["10"]
	"trace": {

For ValidationApiException, meta attribute has errors object that contains validations errors. Every attribute of this object is a name of a request parameter to validate to and value is an array of errors with description.


Extend your default exceptions handler with:

  • \Lanin\Laravel\ApiExceptions\LaravelExceptionHandler for Laravel
  • \Lanin\Laravel\ApiExceptions\LumenExceptionHandler for Lumen

And remove everything else. Example:


namespace App\Exceptions;

use Lanin\Laravel\ApiExceptions\LaravelExceptionHandle;

class Handler extends LaravelExceptionHandle



To use FormRequest extend all your Request classes with \Lanin\Laravel\ApiExceptions\Support\Request. It will automatically support validation errors and pass them to the output.

It also has a very handy helper method validatedOnly() that returns from request only those items that are registered in rules method.


Also you can catch all system exceptions using \Lanin\Laravel\ApiExceptions\Support\RuntimeExceptionsHandler. Just import it to your Http\Kernel $middleware array, and that’s it.

Note! This project can be easily integrated with Laravel-API-Debugger. Just install it, follow instructions, and debug your API!


Please feel free to fork this package and contribute by submitting a pull request to enhance the functionalities.

Star Fork