Skip to content

Errors

The problem every failure answers, each problem type, and when to retry.

Updated

A failed call answers an RFC 9457 problem, Content-Type: application/problem+json:

{
  "type": "https://api.sherpo.io/merchant/docs/errors#conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The call clashes with the current state.",
  "code": "conflict",
  "context": {
    "field": "status",
    "current": "published"
  }
}
  • type names the problem: a URL whose fragment is one of the types below. Branch on the fragment, or on code, never on title or detail.
  • title and status repeat the type’s title and the HTTP status.
  • detail is a sentence for people.
  • code is the error’s code, the same as the type’s fragment. method_not_allowed, range_not_satisfiable, unavailable and client-fault carry none, nor does a 404 for a path no operation answers.
  • context says more, by type: below.

Problem types

not_found

404. Nothing matches a reference the call gave, or the path answers no operation. For a reference, context.kind names the kind not found and context.ref how it was named.

method_not_allowed

405. The path answers other methods, which the Allow header lists.

not_entitled

403. The row exists but is held back from this caller.

not_permitted

The caller may not make this call. context.reason says why, and the status follows it:

Reason Status Meaning
credential 401 No token was sent: send it. Or the token is malformed, unknown, expired or revoked, or its seller left the business: create a new one. See authentication.
scope 403 The token lacks the scope the call needs. See scopes.
principal 403 The token may not act on this store or row, or a file URL is another token’s.
plan 403 The store’s plan doesn’t include it.
paused 403 The business has been past a limit of its plan, or failing to pay for it, for 7 days, so nothing new unlocks (no new grants or customers’ access) until it is back within its limits or pays.
suspended 403 The business is suspended: it has been past a limit of its plan for 14 days while paying, or its plan ended, or it has none. Only billing, deleting stores and the business, removals and reads go on until it is back within its limits or chooses a plan.
limit 429 Too many calls. See rate limits.

conflict

409. The call clashes with the current state: publishing a product that is already published, deleting a row something still uses, reusing an idempotency key with other arguments. context.field names what clashes, context.current its current value, and context.blocked_by, when present, what stands in the way. A write that names what it read (a from, a live, an expect order or a version) and no longer matches also carries context.path, the argument, and context.reason, what it takes there: an attachment id sent where the body’s asset id belongs reads takes the live body's asset id, got its attachment id, and a body changed since reads not the live body's asset id: it changed since, or the id names another file. current names a file only when the token may read files.

invalid

422. An argument is malformed. context.path points at it (["body", "title"]; ["body"] for the body itself; ["headers", "idempotency-key"] for the key; ["query", "access_token"] for a token in a file’s URL, which is never taken) and context.reason says what is wrong. A rich text field outside the format also carries context.excerpt, the text around where it stopped (see rich text). A block refused for its props points at the prop, with context.block, the type of the block holding it, and context.expected, what it takes there (such as one of xs, sm, md, lg, xl, or a number from -1000 to 1000). A quiz’s block refused for a key its type doesn’t take is answered the same way, context.expected listing the keys it takes.

A body over 16 MiB answers 413 with this type; see requests.

range_not_satisfiable

416. A file was asked for with a Range outside it, or with more than one range. Content-Range: bytes */<length> gives its length: ask again for one range within it. See files.

internal

500. The call failed on Sherpo’s side. A read, or a write sent with an Idempotency-Key, may be retried with backoff. Any other write may have landed: read the state back before you try again.

unavailable

503. Sherpo couldn’t be reached for this call. Retry as for internal.

client-fault

500. The API failed while reading your request or writing its answer, and retrying won’t help. The problem says how far the call got:

  • reached_core: false: nothing happened.
  • reached_core: true with core_answer: the call was made, and core_answer is how it ended. ok means it landed (a write was applied, so read it back rather than repeating it), an error code means it was refused, and internal leaves the outcome unknown.

Retrying

Status Retry?
429 Yes, after Retry-After seconds when the answer sends it, else with backoff.
500 internal, 503 Reads and keyed writes, with backoff and a bounded number of attempts. Read the state back before repeating any other write.
500 client-fault No.
Any other 4xx No: change the call first.

No answer sends Retry-After unless the API knows when to retry. A helper that retries what may be retried, waiting as long as the API asks up to a minute; a longer wait, such as a spent daily or monthly quota, comes back at once for you to decide:

// Retries a call refused for a limit; and, when `safe` (a read, or a write with an
// Idempotency-Key), one that failed on the API's side or lost its connection.
// A wait of more than a minute (a spent quota) comes back at once, for the caller to decide.
async function withRetry(call, { safe = false, attempts = 5, longest = 60 } = {}) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await call();
    } catch (error) {
      // fetch rejects with a TypeError when the connection fails; a bug in `call` may too, so it surfaces late.
      const lost = error instanceof TypeError;
      const fault = error.problem?.type?.endsWith('#client-fault');
      const failed = lost || error.status === 503 || (error.status === 500 && !fault);
      if (!(error.status === 429 || (safe && failed)) || attempt === attempts) throw error;
      if (Number.isFinite(error.retryAfter) && error.retryAfter > longest) throw error;
      const wait = Number.isFinite(error.retryAfter)
        ? error.retryAfter * 1000
        : Math.min(30_000, 500 * 2 ** attempt) * (0.5 + Math.random() / 2);
      await new Promise((resolve) => setTimeout(resolve, wait));
    }
  }
}

// Keyed, so a repeat never applies twice: safe to retry.
const product = await withRetry(
  () =>
    sherpo('POST', '/v1/stores/STORE_ID/products', {
      body: { title: 'Ink and wash', category: 'course' },
      key: 'create-ink-and-wash',
    }),
  { safe: true },
);

Type to search…

↑↓ navigate↵ selectEsc close