# Error Handling

Turista is an API-first application, so all errors are returned as JSON. Exception rendering is configured in `bootstrap/app.php`.

## Response envelope

A typical error response follows this shape:

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}
```

For non-validation errors the response may contain only `message`:

```json
{
  "message": "Reservation dates are not available."
}
```

## Mapped exceptions

| Exception type | HTTP status | Notes |
|----------------|-------------|-------|
| ValidationException | 422 | Returned when Form Request validation fails. |
| AuthenticationException | 401 | Returned by `auth:api` middleware. |
| AuthorizationException | 403 | Returned by policies or `verified` middleware. |
| ModelNotFoundException | 404 | Returned when a route-bound model is missing. |
| ReservationUnavailableException | 422 | Returned when requested dates cannot be booked or blocked. |
| HttpException | as set | Generic HTTP exceptions. |

## Exception handler

`bootstrap/app.php` configures the exception handler to render API exceptions as JSON. Validation, authentication, authorization, and model-not-found exceptions are mapped to clean responses. In production, detailed stack traces are hidden (`APP_DEBUG=false`).

## Domain exceptions

`App\Exceptions\ReservationUnavailableException` is thrown by the reservation and availability services when a unit cannot be booked or blocked for the requested dates. Controllers catch this and return a `422` response with a clear message.

## Validation errors

Form Request classes in `app/Http/Requests/` centralize validation rules. When validation fails, Laravel returns a 422 response with the `errors` object keyed by field name.

## Logging

Unexpected exceptions are logged to `storage/logs/laravel.log`. Operators can tail these logs or forward them to a centralized logging service.

## Client guidance

API clients should:

- Check the HTTP status code first.
- Read `message` for a human-readable description.
- Parse `errors` for field-level validation feedback.
- Not rely on the exact text of exception messages in production.