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"
}
}typenames the problem: a URL whose fragment is one of the types below. Branch on the fragment, or oncode, never ontitleordetail.titleandstatusrepeat the type’s title and the HTTP status.detailis a sentence for people.codeis the error’s code, the same as the type’s fragment.method_not_allowed,range_not_satisfiable,unavailableandclient-faultcarry none, nor does a404for a path no operation answers.contextsays 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: truewithcore_answer: the call was made, andcore_answeris how it ended.okmeans it landed (a write was applied, so read it back rather than repeating it), an error code means it was refused, andinternalleaves 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 },
);