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.

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

The request did not include a valid bearer token.

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

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.

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

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

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.

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

• GET /orders/{id}/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.

A validation error pointing at a specific field:

{
  "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):

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