Today, we'll explore how to leverage Laravel 11’s error handling system by implementing the API Problem Specification and enhancing it with custom packages to provide consistent, informative error responses.

Why Upgrade Error Handling?

Laravel 11’s default error handling is good for basic HTTP exceptions, but when working with APIs, aligning with the API Problem Specification provides a more standardized approach. This specification structures error responses, making it easier for API consumers to understand and handle errors effectively.

Enhancing Error Responses with Custom Packages

To take things further, we’ll use the Laravel package I developed for Treblle to improve how error responses are generated. You can find the package on GitHub. This package allows us to generate better-formatted error responses based on the API Problem Specification.

Installation

First, install the package via Composer:

composer require treblle/travel-api-responses

Configuring Laravel 11 to Use the Package

Update Exception Handling: In your bootstrap/app.php, you need to modify the exception handler to use the package’s custom error formatter:

use App\Factories\ErrorFactory;

$app->make(Illuminate\Contracts\Debug\ExceptionHandler::class)->renderable(function ($exception, $request) {
    return ErrorFactory::create($exception, $request);
});

Create an Error Factory

Now, let's define the logic for generating custom error responses by creating an error factory in app/Factories/ErrorFactory.php:

namespace App\Factories;

use Illuminate\Http\JsonResponse;
use Throwable;

class ErrorFactory
{
    public static function create(Throwable $exception, $request): JsonResponse
    {
        $status = $exception->getCode() ?: 500;
        $apiError = [
            'title' => 'An error occurred',
            'detail' => $exception->getMessage(),
            'instance' => $request->url(),
            'status' => $status,
            'type' => 'https://example.com/docs/errors/' . $status
        ];

        return response()->json($apiError, $status);
    }
}

Handling Specific Exceptions

Our goal is to handle different types of errors in a more specific and informative way. Here's how to customize the error responses for different exceptions:

Model Not Found

When a model cannot be found, adjust your ErrorFactory to provide a tailored message:

if ($exception instanceof \Illuminate\Database\Eloquent\ModelNotFoundException) {
    $apiError = [
        'title' => 'Resource Not Found',
        'detail' => 'The resource you are looking for does not exist.',
        'instance' => $request->url(),
        'status' => 404,
        'type' => 'https://example.com/docs/errors/404'
    ];
}

Method Not Allowed

For cases where an HTTP method isn’t allowed for a specific endpoint, handle it like this:

if ($exception instanceof \Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException) {
    $apiError = [
        'title' => 'Method Not Allowed',
        'detail' => 'You are trying to use an HTTP method that is not allowed for this endpoint.',
        'instance' => $request->url(),
        'status' => 405,
        'type' => 'https://example.com/docs/errors/405'
    ];
}

Testing Your Error Responses

After setting up the error handling, you’ll want to test various endpoints and HTTP methods to make sure your API is responding with the correct error formats. Tools like Aspen can be used to send requests and inspect the error responses, ensuring they align with the API Problem Specification. With these updates, your Laravel 11 API will provide standardized, user-friendly error messages that make debugging easier for consumers of your API.