## Errors

### Overview

Every non-2xx response from the Tenant Monolith API uses the same envelope.
This guide describes the envelope, the status codes you can expect, when
each is returned, and how to handle them.

### Response Shape

Errors are returned as a JSON object with a single `errors` key holding one
or more entries. Each entry has the following fields:

- **`code`** *(string, required)* — Machine-readable error type. Stable
across releases and safe to branch on. See [Status Codes](#status-codes)
below for the full set.
- **`detail`** *(string, required)* — Human-readable explanation of this
specific occurrence. Intended for logs and developer-facing surfaces; do
not parse.
- **`source`** *(object, optional)* — Pointer to the input that caused the
error. Returned for validation errors to identify the offending field;
absent otherwise.
  - **`source.pointer`** *(string)* — JSON Pointer path to the offending
attribute, e.g. `/order/package`.


A single response may include multiple entries when more than one field
fails validation. Non-validation errors return exactly one entry.

### Status Codes

#### `401` — `authorization_error`

The request did not include a valid bearer token.

#### `403` — `forbidden`

The token is valid, but the caller is not permitted to perform the requested
action.

#### `404` — `not_found_error`

The requested resource does not exist, or it exists but the caller is not
authorized to access it. The two cases are not distinguished, to avoid
leaking the existence of resources owned by other organizations.

#### `422` — `validation_error`

The request body or parameters failed validation. The response may include
multiple entries — one per offending field — with a `source.pointer`
identifying the attribute.

#### `500` — `internal_error`

An unexpected error occurred while processing the request. Safe to retry.

### Authorization Model

Resources are scoped to the authenticated organization. A request for a
resource owned by another organization returns `404` with `not_found_error`,
identical to the response for a resource that does not exist. This applies
uniformly to every resource endpoint — `GET /orders/{id}`,
`GET /reports/{id}`, `GET /orders/{id}/report`, and any future read.

### Endpoint-Specific 404s

Some endpoints return `404` for reasons beyond authorization, where the
resource itself is not yet available:

- [`GET /orders/{id}/report`](/v1#operation/get-order-report) — the order
exists but has not yet produced a report (typically because it is still in
`waiting_for_applicant` or `pending` status).


These cases are documented on the individual endpoints.

### Examples

A validation error pointing at a specific field:

```json
{
  "errors": [
    {
      "code": "validation_error",
      "detail": "must be one of: starter, essential",
      "source": { "pointer": "/order/package" }
    }
  ]
}
```

A `404` for a resource that does not exist (or that the caller is not
authorized to access):

```json
{
  "errors": [
    {
      "code": "not_found_error",
      "detail": "Report not found"
    }
  ]
}
```