はじめに

Laravelのエラーレスポンスについて書いている記事はいくつか見かけましたが、どれも自分には合わないと感じて自分なりに色々と試してみました。
ソースコードを追ってみて個人的なベストプラクティスを見つけたので共有します。

APIで起きたエラーをJsonで返す

app/Exceptions/Handler.php

protected function prepareResponse($request, Throwable $e)
{
     // /apiから始まるエンドポイントはjsonでエラーを返す
    if ($request->is('api/*')) {
        return parent::prepareJsonResponse($request, $e);
    }
    return parent::prepareResponse($request, $e);
}

ここで一度APIにリクエストを送り、エラー発生させてみてください(abort()が便利)。
下記のようなエラーが返ってくるかと思います。

エラーレスポンス

{
    "message": "エラーのテストです",
    "exception": "Symfony\\Component\\HttpKernel\\Exception\\HttpException",
    "file": "/Applications/MAMP/htdocs/project/vendor/laravel/framework/src/Illuminate/Foundation/Application.php",
    "line": 1122,
    "trace": [
        {
            "file": "/Applications/MAMP/htdocs/project/vendor/laravel/framework/src/Illuminate/Foundation/helpers.php",
            "line": 44,
            "function": "abort",
            "class": "Illuminate\\Foundation\\Application",
            "type": "->"
        }
     ]
}

APIのエラーメッセージをカスタマイズ

Jsonで返ってきたレスポンスをカスタマイズします。convertExceptionToArray()という関数をオーバーライドします。
自分は下記のようにカスタマイズしました。

app/Exceptions/Handler.php

protected function convertExceptionToArray(Throwable $e)
{
    return [
        'message' => $e->getMessage(),
        'exception' => get_class($e),
        'status_code' => $this->isHttpException($e) ? $e->getStatusCode() : 500,
    ];
}

レスポンスを見てみると、このように上手くカスタマイズできました。

エラーレスポンス

{
    "message": "エラーのテストです",
    "exception": "Symfony\\Component\\HttpKernel\\Exception\\HttpException",
    "status_code": 500
}

参考