Laravel API, how to properly handle errors

Question

Anyone know what is the best way to handle errors in Laravel, there is any rules or something to follow ?

Currently i'm doing this :

public function store(Request $request)
{
  $plate = Plate::create($request->all());

  if ($plate) {
    return $this->response($this->plateTransformer->transform($plate));
  } else {
    // Error handling ?
    // Error 400 bad request
    $this->setStatusCode(400);
    return $this->responseWithError("Store failed.");
  }
}

And the setStatusCode and responseWithError come from the father of my controller :

public function setStatusCode($statusCode)
{
    $this->statusCode = $statusCode;

    return $this;
}

public function responseWithError ($message )
{
    return $this->response([
        'error' => [
            'message' => $message,
            'status_code' => $this->getStatusCode()
        ]
    ]);

}

But is this a good way to handle the API errors, i see some different way to handle errors on the web, what is the best ?

Thanks.

You can refer to a similar question https://stackoverflow.com/questions/42958875/laravel-5-4-show-flash-error-and-success-messages-in-different-ways — Leo Rams, Jun 27 '18 at 14:23
In Laravel 9+ for Handle `ModelNotFoundException` exception see https://stackoverflow.com/a/75492554/14344959 — Harsh Patel, Mar 02 '23 at 09:03

rkj · Accepted Answer · 2018-07-25T12:46:21.787

Try this, i have used it in my project (app/Exceptions/Handler.php)

public function render($request, Exception $exception)
{
    if ($request->wantsJson()) {   //add Accept: application/json in request
        return $this->handleApiException($request, $exception);
    } else {
        $retval = parent::render($request, $exception);
    }

    return $retval;
}

Now Handle Api exception

private function handleApiException($request, Exception $exception)
{
    $exception = $this->prepareException($exception);

    if ($exception instanceof \Illuminate\Http\Exception\HttpResponseException) {
        $exception = $exception->getResponse();
    }

    if ($exception instanceof \Illuminate\Auth\AuthenticationException) {
        $exception = $this->unauthenticated($request, $exception);
    }

    if ($exception instanceof \Illuminate\Validation\ValidationException) {
        $exception = $this->convertValidationExceptionToResponse($exception, $request);
    }

    return $this->customApiResponse($exception);
}

After that custom Api handler response

private function customApiResponse($exception)
{
    if (method_exists($exception, 'getStatusCode')) {
        $statusCode = $exception->getStatusCode();
    } else {
        $statusCode = 500;
    }

    $response = [];

    switch ($statusCode) {
        case 401:
            $response['message'] = 'Unauthorized';
            break;
        case 403:
            $response['message'] = 'Forbidden';
            break;
        case 404:
            $response['message'] = 'Not Found';
            break;
        case 405:
            $response['message'] = 'Method Not Allowed';
            break;
        case 422:
            $response['message'] = $exception->original['message'];
            $response['errors'] = $exception->original['errors'];
            break;
        default:
            $response['message'] = ($statusCode == 500) ? 'Whoops, looks like something went wrong' : $exception->getMessage();
            break;
    }

    if (config('app.debug')) {
        $response['trace'] = $exception->getTrace();
        $response['code'] = $exception->getCode();
    }

    $response['status'] = $statusCode;

    return response()->json($response, $statusCode);
}

Always add Accept: application/json in your api or json request.

Thanks for great answer! Not all consumers add `Accept` header that's why instead of `$request->wantsJson()` I check `$request->expectsJson() || $request->isJson()` — Stalinko, Sep 17 '19 at 10:34
No reason to implement what Laravel already handles by default, check my answer — Andrea Mauro, Sep 25 '19 at 08:47
@rkj I am doing same way. Can you provide how to handle syntax error or other errora — Yasin Patel, Apr 08 '21 at 11:31
You can use `$response['message'] = Symfony\Component\HttpFoundation\Response::$statusTexts[$statusCode]` instead of your long switch. — shaedrich, Apr 12 '21 at 15:55

Andrea Mauro · Answer 2 · 2018-12-23T09:35:58.170

Laravel is already able to manage json responses by default.

Withouth customizing the render method in app\Handler.php you can simply throw a Symfony\Component\HttpKernel\Exception\HttpException, the default handler will recognize if the request header contains Accept: application/json and will print a json error message accordingly.

If debug mode is enabled it will output the stacktrace in json format too.

Here is a quick example:

<?php

...

use Symfony\Component\HttpKernel\Exception\HttpException;

class ApiController
{
    public function myAction(Request $request)
    {
        try {
            // My code...
        } catch (\Exception $e) {
            throw new HttpException(500, $e->getMessage());
        }

        return $myObject;
    }
}

Here is laravel response with debug off

{
    "message": "My custom error"
}

And here is the response with debug on

{
    "message": "My custom error",
    "exception": "Symfony\\Component\\HttpKernel\\Exception\\HttpException",
    "file": "D:\\www\\myproject\\app\\Http\\Controllers\\ApiController.php",
    "line": 24,
    "trace": [
        {
            "file": "D:\\www\\myproject\\vendor\\laravel\\framework\\src\\Illuminate\\Routing\\ControllerDispatcher.php",
            "line": 48,
            "function": "myAction",
            "class": "App\\Http\\Controllers\\ApiController",
            "type": "->"
        },
        {
            "file": "D:\\www\\myproject\\vendor\\laravel\\framework\\src\\Illuminate\\Routing\\Route.php",
            "line": 212,
            "function": "dispatch",
            "class": "Illuminate\\Routing\\ControllerDispatcher",
            "type": "->"
        },

        ...
    ]
}

Using HttpException the call will return the http status code of your choice (in this case internal server error 500)

Not sure why this is not the accepted answer. 'My custom error' above replaces $e->getMessage() — TomH, Jan 13 '20 at 07:55
This only works if you are only using API. However my app has also API and normal responses. So I need 2 different ways to handle them - even if I am calling the same code. So I am not throwing 2 different types of exceptions. Or is your code doing that too and I didnt understood it? — alex toader, Apr 12 '21 at 10:33
If your request header contains `Accept: application/json` it will answer with a json error, if you are doing a normal request it will respond with an html error page, showing the exception details if you set your debug on. — Andrea Mauro, Apr 13 '21 at 12:16

user3574492 · Answer 3 · 2018-06-28T16:20:37.817

In my opinion I'd keep it simple.

Return a response with the HTTP error code and a custom message.

return response()->json(['error' => 'You need to add a card first'], 500);

Or if you want to throw a caught error you could do :

   try {
     // some code
    } catch (Exception $e) {
        return response()->json(['error' => $e->getMessage()], 500);
    }

You can even use this for sending successful responses:

return response()->json(['activeSubscription' => $this->getActiveSubscription()], 200);

This way no matter which service consumes your API it can expect to receive the same responses for the same requests.

You can also see how flexible you can make it by passing in the HTTP status code.

score 4 · Answer 4 · answered Jun 06 '22 at 17:36

4

For Laravel 8+ in file App\Exceptions\Hander.php inside method register() paste this code:

$this->renderable(function (Throwable $e, $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => $e->getMessage(),
                'code' => $e->getCode(),
            ], 404);
        }
    });

answered Jun 06 '22 at 17:36

Jean Freitas

209
1
5

can I handle 500 Internal server error & Request class validation error api response globally in laravel 9? – Harsh Patel Mar 02 '23 at 09:04

score 4 · Answer 5 · answered Jun 14 '22 at 22:42

4

If you are using Laravel 8+, you can do it simply by adding these lines in Exception/Handler.php on register() method

    $this->renderable(function (NotFoundHttpException $e, $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Record not found.'
            ], 404);
        }
    });

answered Jun 14 '22 at 22:42

Oussama

165
12

can I handle 500 Internal server error & Request class validation error api response globally in laravel 9? – Harsh Patel Mar 02 '23 at 09:04
Yes, use the same method, with the error exception class. – Oussama May 30 '23 at 12:41

Max Lyu · Answer 6 · 2021-04-12T20:29:20.323

For me, the best way is to use specific Exception for API response.

If you use Laravel version > 5.5, you can create your own exception with report() and render() methods. Use command: php artisan make:exception AjaxResponseException

It will create AjaxResponseException.php at: app/Exceptions/
After that fill it with your logic. For example:

/**
 * Report the exception.
 *
 * @return void
 */
public function report()
{
    \Debugbar::log($this->message);
}

/**
 * Render the exception into an HTTP response.
 *
 * @param  \Illuminate\Http\Request  $request
 * @return JsonResponse|Response
 */
public function render($request)
{
    return response()->json(['error' => $this->message], $this->code);
}

Now, you can use it in your ...Controller with try/catch functionality.
For example in your way:

public function store(Request $request)
{
    try{
        $plate = Plate::create($request->all());

        if ($plate) {
            return $this->response($this->plateTransformer->transform($plate));
        }

        throw new AjaxResponseException("Plate wasn't created!", 404);

    }catch (AjaxResponseException $e) {
        throw new AjaxResponseException($e->getMessage(), $e->getCode());
    }
}

That's enough to make your code more easier for reading, pretty and useful.
Best regards!

score 2 · Answer 7 · answered Feb 26 '20 at 09:12

I think it would be better to modify existing behaviour implemented in app/Exceptions/Handler.php than overriding it.

You can modify JSONResponse returned by parent::render($request, $exception); and add/remove data.

Example implementation:
app/Exceptions/Handler.php

use Illuminate\Support\Arr;

// ... existing code

public function render($request, Exception $exception)
{
    if ($request->is('api/*')) {
        $jsonResponse = parent::render($request, $exception);
        return $this->processApiException($jsonResponse);
    }

    return parent::render($request, $exception);
}

protected function processApiException($originalResponse)
{
    if($originalResponse instanceof JsonResponse){
        $data = $originalResponse->getData(true);
        $data['status'] = $originalResponse->getStatusCode();
        $data['errors'] = [Arr::get($data, 'exception', 'Something went wrong!')];
        $data['message'] = Arr::get($data, 'message', '');
        $originalResponse->setData($data);
    }

    return $originalResponse;
}

score 2 · Answer 8 · answered Dec 12 '21 at 09:06

Well, all answers are ok right now, but also they are using old ways. After Laravel 8, you can simply change your response in register() method by introducing your exception class as renderable:

<?php


namespace Your\Namespace;


use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;


class Handler extends ExceptionHandler
{
    /**
     * Register the exception handling callbacks for the application.
     *
     * @return void
     */
    public function register()
    {
        $this->renderable(function (NotFoundHttpException $e, $request) {
            if ($request->is('api/*')) {
                return response()->json([
                    'message' => 'Record not found.'
                ], 404);
            }
        });
    }
}

Hasnain Abid Khanzada · Answer 9 · 2020-10-07T22:10:47.143

Using some code from @RKJ best answer I have handled the errors in this way:

Open "Illuminate\Foundation\Exceptions\Handler" class and search for a method named "convertExceptionToArray". This method converts the HTTP exception into an array to be shown as a response. In this method, I have just tweaked a small piece of code that will not affect loose coupling.

So replace convertExceptionToArray method with this one

protected function convertExceptionToArray(Exception $e, $response=false)
    {

        return config('app.debug') ? [
            'message' => $e->getMessage(),
            'exception' => get_class($e),
            'file' => $e->getFile(),
            'line' => $e->getLine(),
            'trace' => collect($e->getTrace())->map(function ($trace) {
                return Arr::except($trace, ['args']);
            })->all(),
        ] : [
            'message' => $this->isHttpException($e) ? ($response ? $response['message']: $e->getMessage()) : 'Server Error',
        ];
    }

Now navigate to the App\Exceptions\Handler class and paste the below code just above the render method:

public function convertExceptionToArray(Exception $e, $response=false){

        if(!config('app.debug')){
            $statusCode=$e->getStatusCode();
            switch ($statusCode) {
            case 401:
                $response['message'] = 'Unauthorized';
                break;
            case 403:
                $response['message'] = 'Forbidden';
                break;
            case 404:
                $response['message'] = 'Resource Not Found';
                break;
            case 405:
                $response['message'] = 'Method Not Allowed';
                break;
            case 422:
                $response['message'] = 'Request unable to be processed';
                break;
            default:
                $response['message'] = ($statusCode == 500) ? 'Whoops, looks like something went wrong' : $e->getMessage();
                break;
            }
        }

        return parent::convertExceptionToArray($e,$response);
    }

Basically, we overrided convertExceptionToArray method, prepared the response message, and called the parent method by passing the response as an argument.

Note: This solution will not work for Authentication/Validation errors but most of the time these both errors are well managed by Laravel with proper human-readable response messages.

You can use `$response['message'] = Symfony\Component\HttpFoundation\Response::$statusTexts[$statusCode]` instead of your long switch. — shaedrich, Apr 12 '21 at 15:55

score 1 · Answer 10 · answered Dec 09 '20 at 11:32

In your handler.php This should work for handling 404 Exception.

public function render($request, Throwable $exception ){
    if ($exception instanceof ModelNotFoundException) {
        return response()->json([
            'error' => 'Data not found'
        ], 404);
    }
    return parent::render($request, $exception);
}

score 0 · Answer 11 · answered Nov 28 '22 at 02:04

You don't have to do anything special. Illuminate\Foundation\Exceptions\Handler handles everything for you. When you pass Accept: Application/json header it will return json error response. if debug mode is on you will get exception class, line number, file, trace if debug is off you will get the error message. You can override convertExceptionToArray. Look at the default implementation.

    return config('app.debug') ? [
        'message' => $e->getMessage(),
        'exception' => get_class($e),
        'file' => $e->getFile(),
        'line' => $e->getLine(),
        'trace' => collect($e->getTrace())->map(function ($trace) {
            return Arr::except($trace, ['args']);
        })->all(),
    ] : [
        'message' => $this->isHttpException($e) ? $e->getMessage() : 'Server Error',
    ];

score 0 · Answer 12 · answered Dec 29 '22 at 11:01

As @shahib-khan said,

this happens in debug mode and is handled by Laravel in production mode. you can see base method code in \Illuminate\Foundation\Exceptions\Handler::convertExceptionToArray

  protected function convertExceptionToArray(Throwable $e)
    {
        return config('app.debug') ? [
            'message' => $e->getMessage(),
            'exception' => get_class($e),
            'file' => $e->getFile(),
            'line' => $e->getLine(),
            'trace' => collect($e->getTrace())->map(fn ($trace) => Arr::except($trace, ['args']))->all(),
        ] : [
            'message' => $this->isHttpException($e) ? $e->getMessage() : 'Server Error',
        ];
    }

Therefore, I overrode the the convertExceptionToArray function in app/Exceptions/Handler

of course, still in debug mode, if the exception is thrown, you can track it in the Laravel.log.

 protected function convertExceptionToArray(Throwable $e)
    {
        return  [
            'message' => $this->isHttpException($e) ? $e->getMessage() : 'Server Error',
        ];
    }

score 0 · Answer 13 · answered Jan 24 '23 at 04:57

0

Add header to your API endpoint. which works for me. it will handle the error request properly.

Accept: application/json

answered Jan 24 '23 at 04:57

Najathi

2,529
24
23

Laravel API, how to properly handle errors

13 Answers13

Linked