> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error envelope and request_id, what 400 to 404 and 5xx mean per endpoint family, the response envelopes you will meet, and what to log.

Every failure on this API arrives in the same shape, and the status code alone will not tell you
what to do about it. This page is the decoder: one envelope, the codes inside it, what each status
means for the endpoint family you were calling, and the one field to log so support can find your
exact call.

## What you'll do

**1. Parse one envelope**

Errors are `{ error: { message, error_code }, request_id }` on every service — with one parsing
exception on the token endpoint, below.

**2. Branch on the code, not the message**

`error_code` separates a validation failure from a gateway rejection that shares its status.

**3. Decide retry from the code, not the status class**

A payment-provider failure comes back as `400` or `404`, never `5xx`, so a retry policy keyed
on the status class never fires.

**4. Log request\_id on every response**

Success or failure. It is the fastest way for support to find the call you are describing.

## The error envelope

One shape, on every service — clinical, commerce, and the gateway in front of them.
One exception to the *parsing*, not the shape: the two token-endpoint refusals that quote your
`client_id` back are not valid JSON — see *Read a 401 without guessing*.

```bash curl theme={null}
curl -i "https://api-staging.openloophealth.com/v0.1/patients/00000000-0000-0000-0000-000000000000" \
  -H "authorization: Bearer $TOKEN"
```

```json Response theme={null}
{ "error": { "message": "resource not found", "error_code": "NOT_FOUND" },
  "request_id": "..." }
```

| Field | What it is |
| - | - |
| `error.message` | Human-readable. Often names the offending field (`phone: phone must be E.164 format …`) |
| `error.error_code` | The machine-readable code. Branch on this, not on the message text |
| `request_id` | Present on **every** response, success or failure. Log it |

The envelope carries no `errors[]` array and no per-field map: a request that fails on several
fields still returns a single `message`, with the parts joined inside it.

```json theme={null}
{ "error": { "message": "Validation failed: email: Invalid email; phone: phone must be E.164 format (e.g. +14155552671); birth_date: must be YYYY-MM-DD",
             "error_code": "VALIDATION_ERROR" },
  "request_id": "..." }
```

So parse the envelope, not the sentence. If you want per-field feedback in your own UI, split on
`; ` at your own risk — the format is not contractual, and the single-failure form carries no
`Validation failed:` prefix at all. It is the bare `field: reason`:
`phone: phone must be E.164 format (e.g. +14155552671)`.

> [!TIP]
>
> Locked by check `validation-error-shape`.

## Recipe · Read an error and decide what to do

| `error_code` | Status | What it means | Your move |
| - | - | - | - |
| `VALIDATION_ERROR` | `400` | Your request body or query is wrong | Fix what the message names and resend |
| `BAD_REQUEST` | `400` | A downstream provider rejected it | Read the message — see below |
| `PROVIDER_ERROR` | `400` | The payment provider declined the charge | Ask the patient for another card; see *Payment failure* |
| `UNAUTHORIZED` | `401` | The token you presented was not accepted — missing, malformed, expired, or not verifiable | Re-exchange once, then read the token request's own status |
| `FORBIDDEN` | `403` | Credential not entitled to what you asked for | Check your `audience`; then escalate |
| `DEFAULT_4XX` | `403` | The gateway did not map your path + method | Check the path and the verb |
| `NOT_FOUND` | `404` | No such id — in your tenant or any other, or a `Failed to …` the payment provider raised looking one up | Stop. Do not retry |

Apart from `PROVIDER_ERROR` (the checks cannot decline a card), those are the `error_code` values observed against staging on 2026-09-11; the appointment writes add another, `missing-idempotency-key`, covered in *Retries and idempotency* and in the table under *What comes back*. Treat the list as the ones you will
meet, not as a closed set: branch on the codes you handle, and fall through to "report it with the
`request_id`" for anything else.

## Recipe · Tell a real 404 from a foreign one

A `404` is deliberately opaque. The message is the literal string `resource not found` — it does
not tell you whether the id is wrong, belongs to another tenant, or has been deleted, because
saying so would leak the existence of another customer's record.

The practical consequence: **a `404` is never worth retrying.** It is not a transient condition, and
a second call cannot change the answer. Log it with the id you passed and move on.

Some services return a resource-specific message under the same `NOT_FOUND` code — subscriptions
answer `Subscription not found`, prices answer `Price not found`. A `404` whose message starts
`Failed to …` is a third thing again: the payment provider looked for the object and did not find
it, and its words are passed through — see *Recognise a provider error hiding in a 400*. Branch on
the code; the message is for your logs.

> [!TIP]
>
> Locked by check `not-found-is-opaque`.

## Recipe · Read a 401 without guessing

Three ways of presenting a bad token were probed against staging on 2026-09-11 — no `Authorization`
header, a value that is not a JWT, and a structurally valid JWT the platform cannot verify (a
foreign `aud`, an `exp` already in the past). Each returned the same body:

```json theme={null}
{ "error": { "message": "Unauthorized", "error_code": "UNAUTHORIZED" },
  "request_id": "..." }
```

The one word `Unauthorized` was the whole message every time, so treat a resource call's `401` as
"the token was refused" and get the cause from the request that mints the token. **Re-exchange
once. If the exchange succeeds and the call still returns `401`, the problem is the header you send
on the call. If the exchange fails, its status and message name the cause** — `POST /v0.1/auth/token`
says what is wrong:

| The token request returns | What it means |
| - | - |
| `200` | Credential and `audience` are fine — the problem is the header you send on the call |
| `400` `VALIDATION_ERROR` | A field is missing or malformed, and the message names it: `grant_type: Invalid discriminator value …` for an empty body, `audience is required — specify the target API identifier.` when `audience` is omitted |
| `401` `UNAUTHORIZED` — *Client "…" is not registered.* | The `client_id` is unknown on this host, and that is decided before `audience` is looked at. Check you are using this environment's credential pair |
| `403` `FORBIDDEN` — *Client "…" is not entitled to the requested audience.* | The `audience` you sent is not the one your client is provisioned for |
| `403` `FORBIDDEN` with a message other than *is not entitled* | Your client, its organization or its customer is not active. A `403` about the `Authorization` header is the gateway instead: see *Tell a gateway 403 from a permission 403* below. Re-sending will not help; ask your OLH implementation contact to check the account status, and send the `request_id` from the response (read it as text if the body does not parse) |

> [!TIP]
>
> Locked by check `token-request-failures-are-specific`.

> [!WARNING]
>
> **The two refusals that quote your `client_id` back are not valid JSON.** In the `401` *is not
> registered* and the `403` *is not entitled* bodies, the `client_id` is interpolated into
> `error.message` with unescaped double quotes, so a JSON parser rejects the whole body and
> `error.error_code` is unreachable. Branch on the HTTP status and match the message as text, and pull
> `request_id` out of the text before you log it. The `400` bodies quote no `client_id` and parse
> normally. The `401` case is locked by the check above; the `403` was observed 2026-09-11 with the
> sandbox credential.

> [!WARNING]
>
> **A wrong `audience` is refused by the token endpoint itself.** Sending the staging host as the
> `audience` — the classic mistake — was answered `403 FORBIDDEN`, *is not entitled to the requested
> audience*, by `POST /v0.1/auth/token` (probed 2026-09-11 with the sandbox credential). A `403` from
> the exchange that says *is not entitled* means the request stopped at the `audience`: fix that value
> — it is one fixed string in every environment, see *Getting started* — and re-exchange. When a
> resource call keeps returning `401`, re-run the exchange and read *its* status first.

> [!NOTE]
>
> What is checked here and what is not. The `400` and `401` refusals above run in the check with
> synthetic credentials, and the `200` is the exchange every check in this cookbook starts with. The
> *is not entitled* `403` and the three resource-call `401` bodies are dated observations: the
> conformance harness always presents a valid token minted from the configured credential and never
> writes a real credential into a check, so it cannot re-run them. The `403` for an inactive client,
> organization or customer is not observed or checked here; it is described as OpenLoop reports it.

## Recipe · Tell a gateway 403 from a permission 403

`403` arrives from two entirely different places, and only one of them is about permission.

**The gateway rejected the request before the API saw it.** The message talks about the
`Authorization` header — a missing `Credential`, `Signature` or `SignedHeaders` parameter, or an
invalid `key=value` pair — and `error_code` is `DEFAULT_4XX`. It means the path and method you sent
are not a mapped route. Almost always that is the **wrong verb**, not a missing scope:
`GET /v0.1/checkouts/sessions` produces exactly this, because that path only accepts `POST`. A path
that is not a route at all answers the same way (verified 2026-09-11). Check the reference for the
verb that path accepts before concluding an endpoint is closed to you.

> [!TIP]
>
> Locked by check `unmapped-method-is-403-not-405`.

**Your credential is not entitled to what you asked for.** `error_code` is `FORBIDDEN` and the
message names the entitlement — read it as text, because the body that quotes your `client_id` does
not parse. The case you will actually meet is the `audience` on the token request — see *Read a 401
without guessing* above, which also covers the token `403` for an account that is not active. A
`403` whose message mentions `insufficient_permissions` is the scope version of the same thing — see
*Getting started* for the full three-way split, including payment-provider permission gaps.

## Recipe · Recognise a provider error hiding in a 400

This is the one that costs people a day.

When the payment provider rejects something, the platform **wraps** the failure and returns it as
`400` with `error_code: "BAD_REQUEST"` and a message that starts `Failed to …`:

```json theme={null}
{ "error": { "message": "Failed to create Stripe checkout session: No such price: 'price_…'",
             "error_code": "BAD_REQUEST" },
  "request_id": "..." }
```

**The status is not the constant — the `Failed to …` prefix is.** A provider *lookup miss* —
*No such subscription*, *No such invoice* — is passed through as `404` with
`error_code: "NOT_FOUND"` instead of being wrapped as a `400`: see
[Payment failure](https://openloop.mintlify.site/cookbook/payment-failure.md) for the invoice read, and
[Cancel, pause and refund](https://openloop.mintlify.site/cookbook/cancel-pause-refund.md) for the refund. Both carry the same
`Failed to …` prefix and the provider's own words. So a `Failed to …` message is a provider
failure whatever the status; a `400` means the provider rejected what you sent, and a `404` that it
could not find what you named. A declined charge is a `400` too, but it carries `error_code`
`PROVIDER_ERROR`, not `BAD_REQUEST`.

> [!WARNING]
>
> **A retry policy keyed on `5xx` will never see a provider failure.** The platform accepted your
> request, the provider refused it, and you get a `400` — or a `404` when the refusal was a lookup
> miss. Key your retry decision on the `Failed to …` prefix and `error_code`, never on the status
> class.

A `Failed to …` message means the request was well-formed and something downstream said no. Do not
reshape your payload — read what the provider complained about. The common case is a
`provider_price_id` taken from an archived product, whose ids belong to a previous payment account;
see *Payments and checkout*.

> [!TIP]
>
> Locked by check `provider-error-is-a-400-not-a-5xx`.

## Recipe · Pick the right envelope when you parse a response

Success responses do **not** share one shape, and the difference is by service, not by verb. Typing
a single generic response wrapper is the most common integration bug on this API.

| Shape | Where you meet it | Example |
| - | - | - |
| `{ data, request_id }` | A single resource, and every write | `GET /v0.1/configs`, `POST /v0.1/patients` |
| `{ items, after, request_id }` | Clinical collections, cursor-paginated. `after` is present only when another page exists, so the last page (and any read that fits one page) is `{ items, request_id }` — the same shape at its end, not a third one | `GET /v0.1/patients`, `GET /v0.1/questionnaires`, `GET /v0.1/questionnaire-responses` |
| `{ items, pagination, request_id }` | The product catalogue; `pagination` carries `after`, `before` and `items`, but catalogue paging is not implemented yet, so do not build a cursor loop on it (see *API status*, "Response envelopes differ by endpoint") | `GET /v0.1/products` |
| `{ error, request_id }` | Any failure, from any service | all of the above |

`request_id` is the only field common to all four. Read `data` and `items` as mutually exclusive: a
response carrying one does not carry the other, and the two collection shapes do not share a
pagination field. Measured on staging 2026-09-15 against a two-row cursor-paginated collection:
`limit=1` carries `after`; the same read with `limit=100` returns both rows and no `after`.

> [!TIP]
>
> Locked by check `two-envelopes`.

## What comes back

Every response carries the same small set of fields, success or failure:

| Field | Meaning | You key on it for |
| - | - | - |
| `request_id` | Present on every response, success or failure | Escalation — the one value support needs. Log it on successes too |
| `error.error_code` | The machine-readable cause: `VALIDATION_ERROR`, `NOT_FOUND`, `FORBIDDEN`, `DEFAULT_4XX`, `missing-idempotency-key` | Branching. Never match on `error.message`, which is provider-shaped and changes |
| `error.message` | Human-readable, sometimes the payment provider's own words | Your logs and your support ticket, not your control flow |
| `items` vs `data` | Which envelope this response used | Parsing — see *Pick the right envelope* above |
| HTTP status | The class of failure, which means different things per endpoint family | The table below |

And the status itself means different things depending on which family answered:

| Status | Clinical (`/patients`, `/questionnaires`, `/questionnaire-responses`) | Commerce (`/products`, `/prices`, `/checkouts`, `/subscriptions`, `/invoices`) |
| - | - | - |
| `400` | Body or query rejected. Clinical endpoints also `400` on an **unrecognised query parameter**, and the message lists the ones they accept | Body rejected, **or** a provider failure wrapped as `BAD_REQUEST`. A required filter you omitted lands here too — `GET /v0.1/subscriptions` needs `email`. A declined charge lands here as well, with `error_code` `PROVIDER_ERROR`: on `POST /v0.1/subscriptions` nothing is created. See *Payment failure* |
| `401` | The token you presented was not accepted: missing, malformed, expired, or not verifiable. Re-exchange once; if the exchange itself fails, its status and message name the cause — see *Read a 401 without guessing* | same |
| `403` | Gateway did not map path + method (`DEFAULT_4XX`), or the credential is not entitled (`FORBIDDEN`) | same |
| `404` | Unknown id, opaque | Unknown id, opaque — sometimes with a resource-specific message |
| `5xx` | Not observed against staging during verification (2026-09-11), including for provider failures, which arrive as `400` or `404`. If you do see one: retry once, then report it with the `request_id`. One known exception since: a completed `POST /v0.1/questionnaire-responses` on one staging tenant answers `502` ("eligibility rules are misconfigured") until its rules are re-seeded, while an in-progress submit answers `201` — see *Known gaps and staging* | same |

## What to log

On every response, success or failure, record:

| Field | Why |
| - | - |
| `request_id` | Support cannot find your call quickly without it |
| HTTP status | The class of failure |
| `error.error_code` | What you branched on |
| Full path, **including the `/v0.1` prefix** | Everything partner-facing is under `/v0.1`; logging the bare path loses the one thing that tells you the call was on the partner surface at all |
| Your own correlation id | So you can join the call to the patient journey that made it |

Review what you log from clinical endpoints before you turn it on: their request and response
bodies carry patient data.

## Gotchas

> [!WARNING]
>
> **Do not branch on `error.message`.** It is written for a human and it varies by service for the
> same condition: `resource not found`, `Subscription not found` and `Price not found` all arrive
> under `NOT_FOUND`. Branch on `error_code`; keep the message for your logs and your support ticket.

> [!NOTE]
>
> **`403` is not a reliable signal that you lack access.** The gateway's unmapped-route rejection and
> a genuine entitlement failure share the status. Read `error_code` first: `DEFAULT_4XX` is a
> path-or-verb mistake you can fix yourself; `FORBIDDEN` is a provisioning question for your OLH
> implementation contact.

> [!NOTE]
>
> **A `200` does not confirm your filter was understood.** Clinical endpoints reject an unknown query
> parameter with `400` and name the parameters they accept; commerce endpoints ignore it and return
> `200`. See *API status at a glance*.

> [!NOTE]
>
> Rate limiting was not exercised during verification, so nothing on this page describes it. Do not
> infer a throughput contract from its absence here — ask your OLH implementation contact.

## Related

> [card] [Getting started](https://openloop.mintlify.site/cookbook/getting-started.md)
>
> The first five calls, the envelopes, and the three-way split on `403`

> [card] [Retries and idempotency](https://openloop.mintlify.site/cookbook/retries-and-idempotency.md)
>
> Which calls are safe to send twice, once you have decoded the error

> [card] [FAQ and troubleshooting](https://openloop.mintlify.site/cookbook/faq.md)
>
> Specific error messages, one by one, with the fix for each

> [card] [API status at a glance](https://openloop.mintlify.site/cookbook/api-status.md)
>
> Which endpoints behave as the reference describes, verified against staging


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.