PHPackages                             3sidedcube/laravel-api-errors - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. 3sidedcube/laravel-api-errors

ActiveLibrary[API Development](/categories/api)

3sidedcube/laravel-api-errors
=============================

A lightweight package for handling API error responses.

v2.0(3mo ago)415.5kMITPHPPHP ^8.4CI passing

Since Dec 23Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/3sidedcube/laravel-api-errors)[ Packagist](https://packagist.org/packages/3sidedcube/laravel-api-errors)[ Docs](https://github.com/3sidedcube/laravel-api-errors)[ RSS](/packages/3sidedcube-laravel-api-errors/feed)WikiDiscussions 2.x Synced 1mo ago

READMEChangelog (4)Dependencies (3)Versions (9)Used By (0)

Laravel API Errors
==================

[](#laravel-api-errors)

[![Latest Version on Packagist](https://camo.githubusercontent.com/47afe65dc40aa2273b612a5e9b08c66b1f48e16a6729fb63c534d63bca6d1101/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f337369646564637562652f6c61726176656c2d6170692d6572726f72732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/3sidedcube/laravel-api-errors)[![Total Downloads](https://camo.githubusercontent.com/809fbfa5dab7da02a55cd74bf2e56535868127546a5789cebb446c069b87526b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f337369646564637562652f6c61726176656c2d6170692d6572726f72732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/3sidedcube/laravel-api-errors)[![GitHub Actions](https://github.com/3sidedcube/laravel-api-errors/actions/workflows/run-tests.yml/badge.svg)](https://github.com/3sidedcube/laravel-api-errors/actions/workflows/run-tests.yml/badge.svg)

This package provides an easy way to manage and handle error response for JSON API's.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require 3sidedcube/laravel-api-errors
```

Usage
-----

[](#usage)

There are 2 ways of generating an API error response:

### API Error Exception

[](#api-error-exception)

This package provides an exception called `ApiErrorException` which you can extend. There are 3 methods which can be set (2 of which are required):

- `code()` - This is a short string indicating the error code (required).
- `message()` - A human-readable message providing more details about the error (required).
- `statusCode()` - This HTTP status code of the error response. By default, this is set to 400 and is optional.

Once you have an exception, you can use the `fromException()` method to generate an API error response:

```
use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;
use ThreeSidedCube\LaravelApiErrors\Exceptions\ApiErrorException;

class UserBannedException extends ApiErrorException
{
    /**
     * A short error code describing the error.
     *
     * @return string
     */
    public function code(): string
    {
        return 'user_account_banned';
    }

    /**
     * A human-readable message providing more details about the error.
     *
     * @return string
     */
    public function message(): string
    {
        return 'User account banned.';
    }

    /**
     * The api error status code.
     *
     * @return int
     */
    public function statusCode(): int
    {
        return 403;
    }
}

$exception = new UserBannedException();

// This will return an instance of JsonResponse
$response = ApiErrorResponse::fromException($exception);
```

Returning this response would generate the following json response:

```
{
    "error": {
        "code": "user_account_banned",
        "message": "User account banned."
    }
}
```

#### Automatically returning the exception response

[](#automatically-returning-the-exception-response)

If you want to automatically return the JSON response from the exception, you can add the exception to the `$dontReport`array in your `app/Exceptions/Handler.php` like so:

```
use ThreeSidedCube\LaravelApiErrors\Exceptions\ApiErrorException;

protected $dontReport = [
    ApiErrorException::class,
];
```

### Passing data directly

[](#passing-data-directly)

Alternatively you can use the `create()` method to create an API error response:

```
use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;

// This will return an instance of JsonResponse
$response = ApiErrorResponse::create('user_account_banned', 'User account banned.', 403);
```

Returning this response would generate the following json response:

```
{
    "error": {
        "code": "user_account_banned",
        "message": "User account banned."
    }
}
```

### Additional data

[](#additional-data)

If you would like to pass additional "meta" data to the response, you can use the `meta()` method or pass an array to the create method like so:

```
use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;
use ThreeSidedCube\LaravelApiErrors\Exceptions\ApiErrorException;

class UserBannedException extends ApiErrorException
{
    /**
     * A short error code describing the error.
     *
     * @return string
     */
    public function code(): string
    {
        return 'user_account_banned';
    }

    /**
     * A human-readable message providing more details about the error.
     *
     * @return string
     */
    public function message(): string
    {
        return 'User account banned.';
    }

    /**
     * The api error status code.
     *
     * @return int
     */
    public function statusCode(): int
    {
        return 403;
    }

    /**
     * Any additional metadata to be included in the response.
     *
     * @return array
     */
    public function meta(): array
    {
        return [
            'foo' => 'bar',
        ];
    }
}

$exception = new UserBannedException();

// This will return an instance of JsonResponse
$response = ApiErrorResponse::fromException($exception);
```

or

```
use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;

// This will return an instance of JsonResponse
$response = ApiErrorResponse::create('user_account_banned', 'User account banned.', 403, ['foo' => 'bar']);
```

Returning this response would generate the following json response:

```
{
    "error": {
        "code": "user_account_banned",
        "message": "User account banned.",
        "meta": {
            "foo": "bar"
        }
    }
}
```

### Testing

[](#testing)

```
composer test
```

### Changelog

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Credits
-------

[](#credits)

- [Ben Sherred](https://github.com/benshered)
- [All Contributors](../../contributors)

License
-------

[](#license)

Laravel API Errors is open-sourced software licensed under the [MIT license](LICENSE.md).

###  Health Score

51

—

FairBetter than 96% of packages

Maintenance78

Regular maintenance activity

Popularity27

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 86.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~212 days

Recently: every ~172 days

Total

8

Last Release

119d ago

Major Versions

v1.3.1 → v2.02026-01-19

PHP version history (3 changes)v1.0.0PHP ^8.0

v1.3.1PHP ^8.0|^8.1|^8.2|^8.3

v2.0PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/436e1b99d9a5042fabdc786d56512c70af14ccb5d7f6122c340d33b9f9dd4b94?d=identicon)[3sidedcube](/maintainers/3sidedcube)

---

Top Contributors

[![bensherred](https://avatars.githubusercontent.com/u/22666637?v=4)](https://github.com/bensherred "bensherred (13 commits)")[![javisr](https://avatars.githubusercontent.com/u/505231?v=4)](https://github.com/javisr "javisr (1 commits)")[![javisr3sc](https://avatars.githubusercontent.com/u/208023961?v=4)](https://github.com/javisr3sc "javisr3sc (1 commits)")

---

Tags

3sidedcubelaravel-api-errors

###  Code Quality

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/3sidedcube-laravel-api-errors/health.svg)

```
[![Health](https://phpackages.com/badges/3sidedcube-laravel-api-errors/health.svg)](https://phpackages.com/packages/3sidedcube-laravel-api-errors)
```

###  Alternatives

[mollie/laravel-mollie

Mollie API client wrapper for Laravel & Mollie Connect provider for Laravel Socialite

3624.1M28](/packages/mollie-laravel-mollie)[mll-lab/laravel-graphiql

Easily integrate GraphiQL into your Laravel project

683.2M9](/packages/mll-lab-laravel-graphiql)[esign/laravel-conversions-api

A laravel wrapper package around the Facebook Conversions API

69145.4k](/packages/esign-laravel-conversions-api)[didww/didww-api-3-php-sdk

PHP SDK for DIDWW API 3

1218.2k](/packages/didww-didww-api-3-php-sdk)[surface/laravel-webfinger

A Laravel package to create an ActivityPub webfinger.

113.8k](/packages/surface-laravel-webfinger)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)