---
title: "Errors"
description: "The problem every failure answers, each problem type, and when to retry."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

A failed call answers an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem, `Content-Type: application/problem+json`:

```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` {#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` {#method_not_allowed}

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

### `not_entitled` {#not_entitled}

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

### `not_permitted` {#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](/merchant-api/authentication#refusals). |
| `scope` | `403` | The token lacks the scope the call needs. See [scopes](/merchant-api/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](/merchant-api/rate-limits). |

### `conflict` {#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` {#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](/merchant-api/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](/merchant-api/requests#limits-on-a-request).

### `range_not_satisfiable` {#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](/merchant-api/files).

### `internal` {#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` {#unavailable}

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

### `client-fault` {#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:

```js
// 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 },
);
```

Source: https://docs.sherpo.io/merchant-api/errors/index.mdx
