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 yourclient_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.
; 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
A404 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 — noAuthorization
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:
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.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.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 as400 with error_code: "BAD_REQUEST" and a message that starts Failed to …:
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 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
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.
Related
Getting started
The first five calls, the envelopes, and the three-way split on
403Retries 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

