A failure is an RFC 9457 problem, Content-Type: application/problem+json:
{
"type": "https://api.sherpo.io/customer/docs/errors#not_permitted",
"title": "Not permitted",
"status": 401,
"detail": "The token is missing, expired or revoked.",
"code": "not_permitted",
"context": { "reason": "credential" }
}typenames the problem: a link to the API’s own errors page, whose anchor (after#) is the problem’s name. This page lists the same names.titleanddetailare for people; don’t match on them.codeandcontextcome with every refusal of a call:codeis the name again, andcontextadds what it needs, such as areason, apathor afield. Five answers carry neither:not_foundfor a path that answers no endpoint,method_not_allowed,range_not_satisfiable,unavailableandclient-fault.statusis the HTTP status.
Branch on the name after # in type, then on context.reason or context.path. A name or a reason you don’t know may be added: treat it by its status.
not_found
404. Nothing matches the reference given, the path answers no endpoint, or no store answers on the hostname.
method_not_allowed
405. The path answers other methods, which the Allow header lists.
not_entitled
403. The resource exists, but the customer may not reach it: they hold no access to it. Show what unlocks it (A customer’s library).
not_permitted
401, 403, 429 or 503. context.reason says why:
| Reason | Status | Means |
|---|---|---|
credential |
401 |
Sign the customer in again: the token is missing, expired, revoked, or was issued for another service. With a publishable key: the key is unknown, revoked or another store’s. |
scope |
403 |
The customer didn’t grant the scope this endpoint needs. |
principal |
403 |
The token may not act on this store or row; a publishable key called an endpoint it doesn’t take; a file’s URL is another token’s or key’s, or no longer valid; or an app the store hasn’t verified asked for a saved card, a refund waiver, a default payment method, removing a saved card, or resuming a subscription or changing its plan (Authentication). |
plan |
403 |
The store’s plan doesn’t include it, such as its own front end on Lite. |
paused |
403 |
The store takes no new purchases or unlocks right now. Renewing what the customer already holds still goes through. |
suspended |
503 |
The store isn’t available right now, so nothing works on it until it’s back. Ask again after Retry-After. |
limit |
429 |
A rate limit or quota: see Limits. |
A 401 carries WWW-Authenticate: Bearer, with error="invalid_token" for a token that no longer works; a missing scope’s 403 carries error="insufficient_scope".
conflict
409. The call clashes with the current state. context names the field, its current value and what it’s blocked_by, such as a cart that’s no longer open (status), or a body still being prepared (status, pending).
invalid
422. An argument is malformed. context.path points at it and context.reason says what’s wrong:
context.path |
|
|---|---|
["args", ...] |
An argument of the endpoint, as in ["args", "quantity"]. |
["body"] |
The body itself. |
["headers", "idempotency-key"] |
An Idempotency-Key, which no endpoint here takes. |
["headers", "publishable-key"] |
A malformed publishable key, or one sent with an Authorization header. |
["query", "publishable_key"] |
The same, in a file’s URL: or one empty, sent twice, or other than the header’s. |
["query", "access_token"] |
A token in a file’s URL, which is never taken. |
A body over 16 MiB answers 413 with this type. One nesting deeper than 64 levels, or holding more than 100000 objects and arrays or 100000 values, answers 422.
range_not_satisfiable
416. A file was asked for with a Range outside it, or with anything but one bytes range. Content-Range: bytes */{length} gives the length of what it serves: ask again for one range within it.
internal
500. The call failed inside the service. A read may be retried with backoff, a bounded number of times. A write may have landed, so read the state back before trying again.
unavailable
503. The service couldn’t be reached. Retry as for internal.
client-fault
500. The API failed before or after calling the service, and retrying won’t help. reached_core says whether the call reached the service; when it did, core_answer is what the service answered: ok means the write landed, a code means it was refused, and internal leaves the outcome unknown.
Retries
No answer carries Retry-After unless the service said when to retry. No write takes an Idempotency-Key: after a write that failed with internal or unavailable, or that never answered, read the state back (the cart, the review, the attempt) before trying again.