Skip to content

Errors

Every problem the customer API answers, what it means and what to do about it.

Updated

A failure is an RFC 9457 problem, Content-Type: application/problem+json:

401json
{
  "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" }
}
  • type names 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.
  • title and detail are for people; don’t match on them.
  • code and context come with every refusal of a call: code is the name again, and context adds what it needs, such as a reason, a path or a field. Five answers carry neither: not_found for a path that answers no endpoint, method_not_allowed, range_not_satisfiable, unavailable and client-fault.
  • status is 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.

Type to search…

↑↓ navigate↵ selectEsc close