Laravel API Errors and Exceptions: How to Return Responses

API-based projects are more and more popular, and they are pretty easy to create in Laravel. But one topic is less talked about - it's error handling for various exceptions. API consumers often complain that they get "Server error" but no valuable messages. So, how to handle API errors gracefully? How to return them in "readable" form?

Main Goal: Status Code + Readable Message

For APIs, correct errors are even more important than for web-only browser projects. As people, we can understand the error from browser message and then decide what to do, but for APIs - they are usually consumed by other software and not by people, so returned result should be "readable by machines". And that means HTTP status codes.

Every request to the API returns some status code, for successful requests it's usually 200, or 2xx with XX as other number.

If you return an error response, it should not contain 2xx code, here are most popular ones for errors:

Notice that if we don't specify the status code for return, Laravel will do it automatically for us, and that may be incorrect. So it is advisable to specify codes whenever possible.

In addition to that, we need to take care of human-readable messages. So typical good response should contain HTTP error code and JSON result with something like this:

{
    "error": "Resource not found"
}

Ideally, it should contain even more details, to help API consumer to deal with the error. Here's an example of how Facebook API returns error:

{
  "error": {
    "message": "Error validating access token: Session has expired on Wednesday, 14-Feb-18 18:00:00 PST. The current time is Thursday, 15-Feb-18 13:46:35 PST.",
    "type": "OAuthException",
    "code": 190,
    "error_subcode": 463,
    "fbtrace_id": "H2il2t5bn4e"
  }
}

Usually, "error" contents is what is shown back to the browser or mobile app. So that's what will be read by humans, therefore we need to take care of that to be clear, and with as many details as needed.

Now, let's get to real tips how to make API errors better.

Tip 1. Switch APP_DEBUG=false Even Locally

There's one important setting in .env file of Laravel - it's APP_DEBUG which can be false or true.

If you turn it on as true, then all your errors will be shown with all the details, including names of the classes, DB tables etc.

It is a huge security issue, so in production environment it's strictly advised to set this to false.

But I would advise to turn it off for API projects even locally, here's why.

By turning off actual errors, you will be forced to think like API consumer who would receive just "Server error" and no more information. In other words, you will be forced to think how to handle errors and provide useful messages from the API.

Tip 2. Unhandled Routes - Fallback Method

First situation - what if...