Skip to main content
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.
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.
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).
Locked by check validation-error-shape.

Recipe · Read an error and decide what to do

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.
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:
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:
Locked by check token-request-failures-are-specific.
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.
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.
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.
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 …:
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 for the invoice read, and Cancel, pause and refund 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.
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.
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. 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.
Locked by check two-envelopes.

What comes back

Every response carries the same small set of fields, success or failure: And the status itself means different things depending on which family answered:

What to log

On every response, success or failure, record: Review what you log from clinical endpoints before you turn it on: their request and response bodies carry patient data.

Gotchas

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

Getting started

The first five calls, the envelopes, and the three-way split on 403

Retries and idempotency

Which calls are safe to send twice, once you have decoded the error

FAQ and troubleshooting

Specific error messages, one by one, with the fix for each

API status at a glance

Which endpoints behave as the reference describes, verified against staging