How to properly return errors in your API, Laravel?

Question

API

Greetings. I return errors in my API in this format:

{
    "error" : {
        "error_code" : 1,
        "error_details" : { ... }
    }
}

Well, the corresponding HTTP error code is returned. The content of error_details varies depending on the API method and the error. For example, on a validation error, the error_details field would contain something like this:

{
    "count" => "The count field must be an integer."
}

Is this generally a normal approach?
The main question is how exactly and where to return errors? That is, of course, I can manually return in each method of my API, but this does not look right, besides, if the structure changes, I will have to change all my code. Maybe use an exception handler? In general, I would like to hear your advice and experience on this topic.

Answer 1

I can manually return every method in my API, but it doesn't look right

Why? This is normal practice. Each method is part of the controller, and the controller must return a response. The response in Laravel must be a Response instance (the array is automatically converted to it).
For such cases, Lara provides the ability to create your own response type, for example, ApiResponse. Accordingly, after creation, you will call something like this in the code:
You will do all the formatting in the ApiResponse class.
Actually, to create, you register a new response type in the service provider.

Response::macro('api', function ($code, $data) {
    return new ApiResponse($code, $data);
});

Answer 2

As the main API error indicator, I use HTTP statuses. Laravel supports many cases out of the box:
Thus, manually returning errors will also have to be returned, but in most cases Laravel will do this for you.

Answer 3

There is no single error response format from the http api. There are some contenders, but this is it. It is not necessary to return, it is necessary to throw exceptions and process them in the handler. Better - if there is some one base class AppException, with which you can control the compliance of your own custom errors for the presence of the necessary fields (code, http code, message, meta info). How I do it (so far it’s rolling):
1) from the server I give to each unique error (for example, the one that goes beyond the scope of the validator) my error code, as with error_code. Trivial errors (such as not found or validation) do not have them, since the http code points to it (such as 404 and 422).
2) I also write a message for each exception in the code, which I also give in response during development. On production, I cut down the debug and the message disappears from the response from the server, the http code and "own code" remain.
If we talk only about validation error, then I do it like with error_details, and then the fronter deals with it the way it fits into the design.

Answer 4

I always return a universal mechanism through throw exception for my errors, and suddenly where I miss an exception, it will be processed by the frontend accordingly.
Also, for validation, there are exceptions that will go with your errors in the same format (do not process twice) and axios callbacks work, etc. Http code can be controlled in exception

Answer 5

If you use OAuth 2.0, you can return errors in the same format , adding your custom sections:

{
  "error": "spaceshuttle_crash",
  "error_description": "Houston, we have problems",
  "error_uri": "https://nasa.com/error.html",
  "my_custom_error_code": 42
}