---
title: "Errors"
description: "Every problem the customer API answers, what it means and what to do about it."
---

> 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 failure is an RFC 9457 problem, `Content-Type: application/problem+json`:

```json title="401"
{
  "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`](#not_found) for a path that answers no endpoint, [`method_not_allowed`](#method_not_allowed), [`range_not_satisfiable`](#range_not_satisfiable), [`unavailable`](#unavailable) and [`client-fault`](#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 {#not_found}

`404`. Nothing matches the reference given, the path answers no endpoint, or no store answers on the hostname.

## method_not_allowed {#method_not_allowed}

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

## not_entitled {#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](/customer-api/library#access)).

## not_permitted {#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](/customer-api/authentication#apps-the-store-hasnt-verified)). |
| `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](/customer-api/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 {#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 {#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 {#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 {#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 {#unavailable}

`503`. The service couldn't be reached. Retry as for `internal`.

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

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