In API development, providing clear and structured error responses is crucial for a seamless developer experience. This blog post explores a custom exception handling approach that ensures consistent JSON error responses, making it easier for API consumers to handle errors efficiently.
By default, Laravel returns different structures for different types of errors. This inconsistency can make error handling unpredictable and difficult to manage. A standardized approach helps developers anticipate error structures and build robust integrations.
Here are some examples illustrating the problem with inconsistent error responses in Laravel:
Authentication Failure
When a user is unauthenticated, Laravel returns a response like this:
{
"message": "Unauthenticated."
}
However, this structure lacks a clear error type or additional details that could help API consumers handle the response properly.
Authorization Failure
If a user is authorized incorrectly, Laravel throws an AuthorizationException, resulting in:
{
"message": "This action is unauthorized."
}
Model Not Found
When an API tries to fetch a resource that doesn’t exist, a ModelNotFoundException generates:
{
"message": "No query results for model [User] 123."
}
Validation Error
For validation failures, Laravel returns a completely different structure:
{
"message": "The given data was invalid.",
"errors": {
"email": [
"The email field is required."
],
"password": [
"The password must be at least 8 characters."
]
}
}
Unlike previous responses, this one includes an errors object, making it structurally different from the rest.
To create a consistent API error handling mechanism, we define each error response with:
status: The HTTP status code.errors: An array of errors, each containing:
type: The class name of the exception.message: A descriptive error message.{
"status": 401,
"type": "AuthenticationException",
"error": "Unauthenticated"
}
{
"status": 422,
"type": "ValidationException",
"errors": [
{
"name": "The name field is required."
},
{
"enabled": "The enabled field is required."
},
{
"is_meal": "The is meal field is required."
}
]
}
{
"status": 404,
"type": "NotFoundHttpException",
"error": "Not Found /api/v1/product"
}
In bootstrap/app.php, we define a custom exception handler that processes errors and returns structured responses. Any unhandled exceptions default to a 500 response with a predefined format.
use App\Exceptions\ApiExceptions;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->render(function (Exception $e, Request $request): ?JsonResponse {
$className = get_class($e);
$handlers = ApiExceptions::$handlers;
if (array_key_exists($className, $handlers)) {
$method = $handlers[$className];
return ApiExceptions::$method($e, $request);
}
return response()->json([
'status' => 500,
'type' => class_basename($e),
'error' => $e->getMessage(),
], 500);
});
})
App/Exceptions/ApiExceptions.phpThis class will class a method based on the exception type:
public static array $handlers = [
AuthenticationException::class => 'handleAuthenticationException',
AuthorizationException::class => 'handleAuthorizationException',
ValidationException::class => 'handleValidationException',
ModelNotFoundException::class => 'handleNotFoundException',
NotFoundHttpException::class => 'handleNotFoundException',
MethodNotAllowedHttpException::class => 'handleMethodNotAllowedHttpException',
LazyLoadingViolationException::class => 'handleLazyLoadingViolationException',
ThrottleRequestsException::class => 'handleThrottleRequestsException',
AccessDeniedHttpException::class => 'handleAccessDeniedException',
HttpException::class => 'handleHttpException',
QueryException::class => 'handleQueryException',
PostTooLargeException::class => 'handlePostTooLargeException',
];
Each method can invoke an entry in the logger and return a json response:
public static function handleAuthenticationException(AuthenticationException $e, Request $request): JsonResponse
{
self::logException($e, $request, 'warning');
return self::jsonResponse($e, Response::HTTP_UNAUTHORIZED);
}
private static function logException(Exception $e, Request $request, string $level = 'error'): void
{
Log::$level(class_basename($e), [
'message' => $e->getMessage(),
'file' => $e->getFile(),
'line' => $e->getLine(),
'url' => $request->fullUrl(),
'method' => $request->method(),
'ip' => $request->ip(),
'user_agent' => $request->header('User-Agent'),
]);
}
private static function jsonResponse(Exception $e, int $status, ?string $customMessage = null): JsonResponse
{
return response()->json([
'status' => $status,
'type' => class_basename($e),
'error' => $customMessage ?? $e->getMessage(),
], $status);
}
Putting it all together:
<?php
declare(strict_types=1);
namespace App\Exceptions;
use Exception;
use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Illuminate\Database\LazyLoadingViolationException;
use Illuminate\Database\QueryException;
use Illuminate\Http\Exceptions\PostTooLargeException;
use Illuminate\Http\Exceptions\ThrottleRequestsException;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\HttpKernel\Exception\HttpException;
use Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
class ApiExceptions
{
/**
* @var array<string, string>
*/
public static array $handlers = [
AuthenticationException::class => 'handleAuthenticationException',
AuthorizationException::class => 'handleAuthorizationException',
ValidationException::class => 'handleValidationException',
ModelNotFoundException::class => 'handleNotFoundException',
NotFoundHttpException::class => 'handleNotFoundException',
MethodNotAllowedHttpException::class => 'handleMethodNotAllowedHttpException',
LazyLoadingViolationException::class => 'handleLazyLoadingViolationException',
ThrottleRequestsException::class => 'handleThrottleRequestsException',
AccessDeniedHttpException::class => 'handleAccessDeniedException',
HttpException::class => 'handleHttpException',
QueryException::class => 'handleQueryException',
PostTooLargeException::class => 'handlePostTooLargeException',
];
public static function handleAuthenticationException(AuthenticationException $e, Request $request): JsonResponse
{
self::logException($e, $request, 'warning');
return self::jsonResponse($e, Response::HTTP_UNAUTHORIZED);
}
public static function handleAuthorizationException(Exception $e, Request $request): JsonResponse
{
self::logException($e, $request, 'warning');
return self::jsonResponse($e, Response::HTTP_FORBIDDEN);
}
public static function handleValidationException(ValidationException $e): JsonResponse
{
return self::jsonResponse($e, Response::HTTP_UNPROCESSABLE_ENTITY, $e->errors());
}
public static function handleNotFoundException(Exception $e, Request $request): JsonResponse
{
return self::jsonResponse($e, Response::HTTP_NOT_FOUND, 'Not Found '.$request->getRequestUri());
}
public static function handleMethodNotAllowedHttpException(Exception $e): JsonResponse
{
return self::jsonResponse($e, Response::HTTP_METHOD_NOT_ALLOWED);
}
public static function handleLazyLoadingViolationException(LazyLoadingViolationException $e, Request $request): JsonResponse
{
return self::jsonResponse($e, Response::HTTP_UNPROCESSABLE_ENTITY);
}
public static function handleThrottleRequestsException(ThrottleRequestsException $e, Request $request): JsonResponse
{
self::logException($e, $request, 'warning');
return self::jsonResponse($e, Response::HTTP_TOO_MANY_REQUESTS, 'Too many requests, please slow down.');
}
public static function handleAccessDeniedException(AccessDeniedHttpException $e, Request $request): JsonResponse
{
self::logException($e, $request, 'warning');
return self::jsonResponse($e, Response::HTTP_FORBIDDEN, 'Access denied.');
}
public static function handleHttpException(HttpException $e, Request $request): JsonResponse
{
self::logException($e, $request);
return self::jsonResponse($e, $e->getStatusCode());
}
public static function handleQueryException(QueryException $e, Request $request): JsonResponse
{
self::logException($e, $request);
return self::jsonResponse($e, Response::HTTP_INTERNAL_SERVER_ERROR, 'A database error occurred.');
}
public static function handlePostTooLargeException(PostTooLargeException $e, Request $request): JsonResponse
{
self::logException($e, $request, 'warning');
return self::jsonResponse($e, Response::HTTP_REQUEST_ENTITY_TOO_LARGE, 'The uploaded file is too large.');
}
private static function logException(Exception $e, Request $request, string $level = 'error'): void
{
Log::$level(class_basename($e), [
'message' => $e->getMessage(),
'file' => $e->getFile(),
'line' => $e->getLine(),
'url' => $request->fullUrl(),
'method' => $request->method(),
'ip' => $request->ip(),
'user_agent' => $request->header('User-Agent'),
]);
}
/**
* @param array<string, array<int, string>>|array<int, string>|string|null $customMessage
*/
private static function jsonResponse(Exception $e, int $status, null|array|string $customMessage = null): JsonResponse
{
return response()->json([
'status' => $status,
'type' => class_basename($e),
$customMessage && is_array($customMessage) ? 'errors' : 'error' => $customMessage ?? $e->getMessage(),
], $status);
}
}
With this structured error format, API tests need to verify the new structure. Instead of checking for arbitrary keys, it’s recommended to:
All custom application code should always be tested, the following tests test each method using Pest
tests/Unit/ApiExceptionsTest.php
<?php
use App\Exceptions\ApiExceptions;
use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Database\LazyLoadingViolationException;
use Illuminate\Database\QueryException;
use Illuminate\Http\Exceptions\PostTooLargeException;
use Illuminate\Http\Exceptions\ThrottleRequestsException;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\HttpKernel\Exception\HttpException;
use Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
beforeEach(function () {
$this->request = Mockery::mock(Request::class);
$this->request->shouldReceive('fullUrl')->andReturn('http://test.com');
$this->request->shouldReceive('method')->andReturn('GET');
$this->request->shouldReceive('ip')->andReturn('127.0.0.1');
$this->request->shouldReceive('header')->andReturn('Mozilla/5.0');
});
test('handleAuthenticationException', function () {
$exception = new AuthenticationException('Unauthenticated');
$response = ApiExceptions::handleAuthenticationException($exception, $this->request);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(401);
});
test('handleAuthorizationException', function () {
$exception = new AuthorizationException('Forbidden');
$response = ApiExceptions::handleAuthorizationException($exception, $this->request);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(403);
});
test('handleValidationException', function () {
$exception = ValidationException::withMessages(['field' => ['Validation error']]);
$response = ApiExceptions::handleValidationException($exception);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(422);
});
test('handleNotFoundException', function () {
$request = Mockery::mock(Request::class);
$request->shouldReceive('getRequestUri')->andReturn('/test-uri');
$exception = new NotFoundHttpException('Not Found');
$response = ApiExceptions::handleNotFoundException($exception, $request);
$responseData = json_decode($response->getContent(), true);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(404)
->and($responseData)->toMatchArray([
'status' => 404,
'type' => 'NotFoundHttpException',
'error' => 'Not Found /test-uri',
]);
});
test('handleMethodNotAllowedHttpException', function () {
$exception = new MethodNotAllowedHttpException([], 'Method Not Allowed');
$response = ApiExceptions::handleMethodNotAllowedHttpException($exception);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(405);
});
test('handleLazyLoadingViolationException', function () {
$exception = Mockery::mock(LazyLoadingViolationException::class);
$response = ApiExceptions::handleLazyLoadingViolationException($exception, $this->request);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(422);
});
test('handleThrottleRequestsException', function () {
$exception = new ThrottleRequestsException('Too Many Requests');
$response = ApiExceptions::handleThrottleRequestsException($exception, $this->request);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(429);
});
test('handleAccessDeniedException', function () {
$exception = new AccessDeniedHttpException('Access Denied');
$response = ApiExceptions::handleAccessDeniedException($exception, $this->request);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(403);
});
test('handleHttpException', function () {
$exception = new HttpException(500, 'Internal Server Error');
$response = ApiExceptions::handleHttpException($exception, $this->request);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(500);
});
test('handleQueryException', function () {
$exception = Mockery::mock(QueryException::class);
$response = ApiExceptions::handleQueryException($exception, $this->request);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(500);
});
test('handlePostTooLargeException', function () {
$exception = new PostTooLargeException('Payload Too Large');
$response = ApiExceptions::handlePostTooLargeException($exception, $this->request);
expect($response)->toBeInstanceOf(JsonResponse::class)
->and($response->getStatusCode())->toBe(413);
});
Implementing structured exception handling improves API consistency, simplifies debugging, and enhances developer experience.
What do you think? Let’s discuss this further in the comments or on social media.
Subscribe to my newsletter for the latest updates on my books and digital products.
Find posts, tutorials, and resources quickly.
Subscribe to my newsletter for the latest updates on my books and digital products.
