Skip to content
Antares

Error Handling

Every exception thrown while handling a request (in middleware, guards, controllers or your services) is caught by the ErrorHandler and turned into a JSON error response, loosely following RFC 7807 Problem Details.

The rule is simple: an error’s message is only shown if the exception was meant for the client. Everything else becomes a generic 500, so a database error or a bug never leaks details to your users.

ExceptionStatustitle in the response
ValidationException (a DTO broke a rule)422Validation failed, plus an errors map
HydrationException (the body doesn’t fit the DTO)400its message, e.g. Missing required parameter: email
Unknown route404Route not found
Known route, wrong HTTP method405, with an Allow headerMethod not allowed
HttpException($code, $message), or anything implementing HttpExceptionInterface$codeits message
An exception listed in ->exceptions([...])the mapped statusits message, or the mapped one
Anything else500Internal Server Error

The messages of the rows above “Anything else” are shown in every environment. You decide what the client sees by choosing which exception to throw.

The simplest way. The status code comes first:

use Antares\Exceptions\HttpException;
throw new HttpException(403, 'Forbidden');
throw new HttpException(404, 'User not found');
throw new HttpException(409, 'Email already in use');

For errors you throw in several places, implement HttpExceptionInterface. It works with any base class:

use Antares\Exceptions\HttpExceptionInterface;
final class EmailAlreadyTaken extends \DomainException implements HttpExceptionInterface
{
public function __construct()
{
parent::__construct('Email already in use');
}
public function getStatusCode(): int
{
return 409;
}
}
throw new EmailAlreadyTaken(); // 409 "Email already in use"

HttpException itself implements this interface. A status code outside 400–599 is treated as an unexpected error (500).

For exceptions you can’t change, such as those thrown by a library, map them on the application:

use Illuminate\Database\Eloquent\ModelNotFoundException;
use Illuminate\Database\QueryException;
Application::create(__DIR__ . '/..')
->exceptions([
ModelNotFoundException::class => 404, // keeps the exception's message
QueryException::class => [409, 'Conflict'], // replaces it with your own
])
->run();

Subclasses match too, and the first matching entry wins. The map is checked on boot, so a typo (a class that isn’t an exception, or a status outside 400–599) fails immediately.

Only replace the message ([status, 'message']) when the original might contain internal details, as a QueryException’s SQL does.

In development you want to see what went wrong. With APP_DEBUG on, a 500 also includes a debug block with the real error:

{
"type": "https://antares.dev/errors",
"title": "Internal Server Error",
"status": 500,
"debug": {
"message": "SQLSTATE[42S02]: Base table or view not found",
"exception": "PDOException",
"file": "app/Repositories/UserRepository.php:42",
"trace": ["app/Controllers/UserController.php:18", "…"]
}
}

file and trace are relative to your project root. If the exception wraps another one, the wrapped error is shown under debug.previous.

APP_ENVAPP_DEBUGError details in 500 responses
local (or anything but production)not setshown
productionnot sethidden
anytrueshown
anyfalsehidden
APP_DEBUG=false # e.g. a staging server that runs APP_ENV=local

Every 5xx response is logged with the full exception, in every environment:

  • If a Psr\Log\LoggerInterface is registered in the container, it is logged there at error level, with the exception in the exception context key. The Monolog bridge registers one automatically.
  • Otherwise it is written with PHP’s error_log(), including the stack trace.

4xx responses are not logged: they are the client’s mistake, not your app’s.

Every error response is JSON (Content-Type: application/json) with type, title and status:

{
"type": "https://antares.dev/errors",
"title": "User not found",
"status": 404
}

Validation errors also include an errors map with every failed rule per field:

{
"type": "https://antares.dev/errors",
"title": "Validation failed",
"status": 422,
"errors": {
"email": ["The value must be a valid email address."],
"name": ["The value must be at least 2 characters long."]
}
}