Managing API Exception Handling with Custom Formats in bootstrap/app.php

I created a function called getJsonResponse inside app.php to handle the filtering logic. However, this approach makes app.php quite large. I’m considering extracting the response logic into a separate class or helper function instead. What do you think? https://gist.github.com/mina20088/df72bf0eb161024203cef160e7c02196

Extracting this logic to a separate class is exactly what I proposed.

Two considerations:

1. don't you reinvent the wheel? I mean, do you really need such a complex JSON in API response?
   Also, why you duplicate HTTP response code and type in JSON? These values can be taken from HTTP status code and phrase itself. I mean, if a user gets HTTP response 404 Not Found why duplicate it in JSON like this:

{
    ...
    "type": "NOT_FOUND_EXCEPTION",
    "statusCode": 404,
    ...
}

2. the code building the response is highly duplicated - it creates many almost identical arrays with only some exception-specific fields. You can simplify it by building an array with all common fields and transform specific fields afterwards.

Could you please provide me with a schema that I can use for all my responses—including errors, data, and other cases? Also, if possible, could you include a code example to help me better understand point number 2? Thank you in advance.

For point 1, you mean that when consuming the API from a SPA like Vue using Axios or the Fetch API, the response already includes the 404 status, so there’s no need to include it again, right?

Ok, I will when I'm at a computer, tomorrow.

What data do you think your API users need? Do they really need traces and file names and line numbers of your code? Or it is just for you while developing?

response already includes the 404 status, so there’s no need to include it again, right?

Yes, HTTP response already has status code which describes what is wrong quite well. 404 means "not found", no need to have it again inside response body unless you have special needs.

Thank you very much. This is my first time creating an API, so I’m not yet familiar with the conventions.

First of all, why you implement your own structure? What is wrong with Laravel builtin JSON errors?

what do you think if i made the method like this

protected function getJsonResponse(\Throwable $e): JsonResponse
{
    // Common base structure for any error response
    $response = [
        'message' => $e->getMessage(),
        'timestamp' => now()->toIso8601String(),
        // other common fields you want to include
    ];

    // Customize base response by exception type
    if ($e instanceof NotFoundException) {
        $response['details'] = 'Resource not found';
    } elseif ($e instanceof ValidationException) {
        $response['details'] = $e->errors(); // example for validation errors
    } else {
        $response['details'] = 'An unexpected error occurred';
    }

    // Map exception to HTTP status
    $status = $this->getStatusCode($e);

    // Return JSON response WITHOUT duplicating status code/type in JSON
    return response()->json($response, $status);
}

protected function getStatusCode(\Throwable $e): int
{
    if ($e instanceof NotFoundException) {
        return 404;
    } elseif ($e instanceof ValidationException) {
        return 422;
    }
    return 500; // default server error
}

i just want all of my response to be same , think this is one of the restful api convinsions , correct me if i am wrong

My suggestion is to stick to standard Laravel responses until you really know why you need a custom structure. Otherwise you can spend a lot of time reinventing the wheel while clients of your API don't need it at all.

Simple abort(404, 'I haven\'t found anything'); will give you nice response:

HTTP/1.1 404 Not Found

{
    "message": "I haven't found anything"
}

If you have APP_DEBUG=true in .env this JSON will be appended with stack trace which is useful for debugging. That's all, do you really need something more complex?

If you want to stick to your structure, I would go with something like this:

class ExceptionSchema
{
    public static function render (\Throwable $exception, Request $request): JsonResponse 
    {
        return response()->json((new self)->jsonSchema($exception, $request));
    }


    public function jsonSchema (\Throwable $exception, Request $request): array
    {
        return [
            'success'    => false,
            'type'       => $this->handleType($exception),
            'statusCode' => $this->handleStatusCode($exception),
            'message'    => $exception->getMessage(),
            'data'       => null,
            'errors'     => [
                'message' => $exception->getMessage(),
                'code'    => $exception->getCode(),
                'file'    => $exception->getFile(),
                'line'    => $exception->getLine(),
                'trace'   => $exception->getTrace(),
            ],
            'meta'       => [
                'controller' => $request->route()->getControllerClass(),
                'action'     => $request->route()->getActionName(),
                'parameters' => $request->route()->parameters() ?? null,
            ],
            'timestamp'  => Carbon::now()->toDateTimeString(),
        ];
    }


    public function handleType (\Throwable $exception): ?string
    {
        return match (get_class($exception)) {
            NotFoundHttpException::class     => 'MY_CUSTOM_TYPE_FOR_404_ERROR',
            AccessDeniedHttpException::class => 'MY_CUSTOM_TYPE_FOR_403_ERROR',
            // ...
            default => null,
        };
    }


    public function handleStatusCode (\Throwable $exception): int
    {
        return match (get_class($exception)) {
            NotFoundHttpException::class     => 404,
            AccessDeniedHttpException::class => 403,
            // ...
            default => 500,
        };
    }
}

After that use it in app.php:

$exceptions->render(ExceptionSchema::render(...));

But again, Laravel already does the same inside.

i just want all of my response to be same , think this is one of the restful api convinsions , correct me if i am wrong

@minaremonshaker Your responses will be the same if you just let Laravel’s exception handler do what it says on the tin, and let it handle exceptions.

And as someone else has pointed out, there’s absolutely zero point including things like 'success' => false and 'statusCode' => ResponseAlias::HTTP_NOT_FOUND in your response body when that’s the entire point of the response status code. You don’t need statusCode in the body when it’s in the headers. You also don’t need a success key because if I get a 4xx or 5xx response, then it’s clear it wasn’t successful.

OK, thank you martin got the point