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.1.0(3mo ago)011MITPHPPHP ^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 1mo ago

READMEChangelog (1)Dependencies (6)Versions (2)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` or `12.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

34

—

LowBetter than 77% of packages

Maintenance82

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

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

Unknown

Total

1

Last Release

105d 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 (9 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

[spatie/laravel-query-builder

Easily build Eloquent queries from API requests

4.4k26.9M220](/packages/spatie-laravel-query-builder)[essa/api-tool-kit

set of tools to build an api with laravel

52680.5k](/packages/essa-api-tool-kit)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[simplestats-io/laravel-client

Client for SimpleStats!

4515.5k](/packages/simplestats-io-laravel-client)[label84/laravel-auth-log

Log user authentication actions in Laravel.

3654.0k](/packages/label84-laravel-auth-log)

PHPackages © 2026

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