Laravel API Errors and Exceptions: How to Return Responses

Tutorial last revisioned on March 15, 2024 with Laravel 11

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:

Status CodeMeaning
404Not Found (page or other resource doesn't exist)
401Not authorized (not logged in)
403Logged in but access to requested area is forbidden
400Bad request (something wrong with URL or parameters)
422Unprocessable Entity (validation failed)
500General server error

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...

The full tutorial [10 mins, 1891 words] is only for Premium Members

Login Or Become a Premium Member for $129/year or $29/month
What else you will get:
  • 68 courses (1183 lessons, total 43 h 18 min)
  • 90 long-form tutorials (one new every week)
  • access to project repositories
  • access to private Discord

Recent New Courses