PHPackages                             hatchyu/laravel-api-exceptions - 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. hatchyu/laravel-api-exceptions

ActiveLibrary[API Development](/categories/api)

hatchyu/laravel-api-exceptions
==============================

API-first reusable JSON exception classes for Laravel with proper HTTP status codes

v0.2.0(2mo ago)03.5kMITPHPPHP ^8.2

Since Feb 2Pushed 2mo agoCompare

[ Source](https://github.com/rajeshmk/laravel-api-exceptions)[ Packagist](https://packagist.org/packages/hatchyu/laravel-api-exceptions)[ RSS](/packages/hatchyu-laravel-api-exceptions/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (13)Versions (3)Used By (0)

Laravel API Exceptions
======================

[](#laravel-api-exceptions)

[![Packagist Version](https://camo.githubusercontent.com/815ee613cadc37b801ef93344a0c7c43559f01c9f9f70f9527f6cbba521825a2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f686174636879752f6c61726176656c2d6170692d657863657074696f6e73)](https://camo.githubusercontent.com/815ee613cadc37b801ef93344a0c7c43559f01c9f9f70f9527f6cbba521825a2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f686174636879752f6c61726176656c2d6170692d657863657074696f6e73)[![PHP Version](https://camo.githubusercontent.com/7821843033301c97a8adf05bec0490db9b1dcbd8050774e30571b784da196169/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f686174636879752f6c61726176656c2d6170692d657863657074696f6e73)](https://camo.githubusercontent.com/7821843033301c97a8adf05bec0490db9b1dcbd8050774e30571b784da196169/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f686174636879752f6c61726176656c2d6170692d657863657074696f6e73)[![License](https://camo.githubusercontent.com/81bbbd3e1880c60262e5dfbfac204aed0edca9b5e4da8352499b76ec4edd6028/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f686174636879752f6c61726176656c2d6170692d657863657074696f6e73)](https://camo.githubusercontent.com/81bbbd3e1880c60262e5dfbfac204aed0edca9b5e4da8352499b76ec4edd6028/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f686174636879752f6c61726176656c2d6170692d657863657074696f6e73)

A small library of reusable API exception classes for Laravel apps. Each exception implements `Responsable`, so throwing one returns a JSON error response with an appropriate HTTP status code.

**Requirements**

- PHP `^8.2`
- Laravel `11.x`, `12.x` or `13.x`

**Install**

```
composer require hatchyu/laravel-api-exceptions
```

The service provider is auto-discovered by Laravel.

**Usage**

```
use Hatchyu\ApiExceptions\Http\BadRequestException;

// Returns a 400 JSON response:
// { "error": { "message": "Invalid payload." } }
throw new BadRequestException('Invalid payload.');
```

If you omit a message, a default is generated from the class name, for example `BadRequestException` becomes "Bad request.".

**Factory Helpers**Some domain exceptions expose convenient factory methods for consistent messages:

```
use Hatchyu\ApiExceptions\General\FileTooLargeException;
use Hatchyu\ApiExceptions\General\FileUploadException;
use Hatchyu\ApiExceptions\General\UnsupportedFileTypeException;
use Hatchyu\ApiExceptions\Model\ModelNotFoundException;
use Hatchyu\ApiExceptions\Model\ModelCreateException;
use Hatchyu\ApiExceptions\Model\ModelUpdateException;
use Hatchyu\ApiExceptions\Model\ModelDeleteException;

throw FileTooLargeException::for('invoice.pdf');
throw FileUploadException::for('invoice.pdf');
throw UnsupportedFileTypeException::forFile('invoice.pdf', 'application/pdf');
throw ModelNotFoundException::forModel(Customer::class, 3);
throw ModelCreateException::forModel(Customer::class, 'Email already exists');
throw ModelUpdateException::forModel($customer);
throw ModelDeleteException::forModel($customer, 'Customer has active orders');

// Non-"id" primary keys are resolved automatically from the model instance.
// Example output: "Failed to update Order (order_id: ORD-1001)."
throw ModelUpdateException::forModel($order);
```

Note: `DocumentUploadException` is deprecated in favor of `FileUploadException`.

**Common Exceptions**

- `BadRequestException` (400)
- `UnauthorizedException` (401)
- `ForbiddenException` (403)
- `NotFoundException` (404)
- `ConflictException` (409)
- `UnprocessableEntityException` (422)
- `TooManyRequestsException` (429)
- `InternalServerErrorException` (500)
- `ServiceUnavailableException` (503)

**Namespaces**

- `Hatchyu\ApiExceptions\Http` (top-level HTTP status exceptions)
- `Hatchyu\ApiExceptions\Auth` (authentication/authorization helpers)
- `Hatchyu\ApiExceptions\General` (domain-friendly helpers)
- `Hatchyu\ApiExceptions\Model` (model operation helpers)
- `Hatchyu\ApiExceptions\Validation` (validation helpers)

**Custom Exceptions**Create your own by extending `Hatchyu\ApiExceptions\Base\ApiBaseException` and overriding `customHttpCode()`.

**Localization**This package ships English translations in `resources/lang/en`. You can override them in your app by placing files under `resources/lang/{locale}/vendor/api-exceptions`.

**Publishing Translations**To publish the translation files into your application for editing:

```
php artisan vendor:publish --tag=api-exceptions-translations
```

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance84

Actively maintained with recent releases

Popularity24

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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 ~67 days

Total

2

Last Release

84d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/743e9d5b6f56260847460cad4084ed9c341d791eaad645f0d318f686786d72ac?d=identicon)[rajeshmk](/maintainers/rajeshmk)

---

Top Contributors

[![rajeshmk](https://avatars.githubusercontent.com/u/227696?v=4)](https://github.com/rajeshmk "rajeshmk (10 commits)")

###  Code Quality

Static AnalysisRector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/hatchyu-laravel-api-exceptions/health.svg)

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

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M132](/packages/laravel-pulse)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[mike-bronner/laravel-model-caching

Automatic caching for Eloquent models.

2.4k91.9k1](/packages/mike-bronner-laravel-model-caching)[api-platform/laravel

API Platform support for Laravel

58171.6k14](/packages/api-platform-laravel)[essa/api-tool-kit

set of tools to build an api with laravel

53390.1k](/packages/essa-api-tool-kit)

PHPackages © 2026

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