> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.papertracc.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.papertracc.com/_mcp/server.

# Errors

A failed request returns a non-2xx status and this envelope:

```json
{
  "status": false,
  "message": "Api key owner is not a member of this workspace."
}
```

`message` says what went wrong. Some responses add fields: `402` and `403` responses carry an `error_code`, and `403` responses name the missing `permission` or the disabled `service`.

## Status codes

| Status | Meaning                                                                                                                                                                                                               |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The request is malformed: a required header or field is missing, the body is not valid JSON, or a field failed validation. The message names the field.                                                               |
| `401`  | The API key is missing or invalid, the key owner has left the organisation, the key owner is not a member of the workspace in the `identity` header, or a public key was used on an endpoint that needs a secret key. |
| `402`  | The workspace's plan does not include what the request needs. `error_code` says what.                                                                                                                                 |
| `403`  | The key is not allowed to do this. `error_code` says why.                                                                                                                                                             |
| `404`  | The record, sales channel or cart does not exist, or is not visible to this request.                                                                                                                                  |
| `422`  | The request was understood but a rule stopped it, for example an item that is out of stock or a promotion code that does not apply.                                                                                   |
| `423`  | The accounting period is locked, so the record cannot be created or changed. Core endpoints only.                                                                                                                     |
| `429`  | Too many requests. See [Rate limits](#rate-limits).                                                                                                                                                                   |
| `500`  | Something went wrong on our side. Retry later.                                                                                                                                                                        |
| `503`  | A dependency was briefly unavailable, for example sending a sign-in code. Retry shortly.                                                                                                                              |

## Error codes

| Status | `error_code`                 | Meaning                                                                                                                                                  |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `402`  | `OPEN_API_NOT_ENABLED`       | The workspace's subscription plan does not include the Open API.                                                                                         |
| `402`  | `MULTI_CURRENCY_NOT_ENABLED` | The request uses a currency other than the workspace's base currency, and the plan does not include multi-currency. Core endpoints only.                 |
| `402`  | `STORAGE_LIMIT_EXCEEDED`     | The workspace has reached a limit of its plan. Core endpoints only.                                                                                      |
| `403`  | `PERMISSION_DENIED`          | The key owner's role lacks the permission the endpoint needs. `permission` names it, so a workspace manager can add it to the role. Core endpoints only. |
| `403`  | `SERVICE_DISABLED`           | The service the endpoint belongs to is turned off for the workspace. `service` names it. Core endpoints only.                                            |

```json
{
  "status": false,
  "message": "The API key owner's role does not allow this action",
  "error_code": "PERMISSION_DENIED",
  "permission": "can_create_sales_invoice"
}
```

Every Core endpoint lists the permission it needs in its description. Storefront endpoints do not check role permissions.

## Storefront errors

Storefront messages are written so that most can be shown to a shopper as they are.

| Status | Example message                                         | When                                                                                     |
| ------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `400`  | `Channel header not found.`                             | The `channel` header is missing.                                                         |
| `404`  | `sales channel not found`                               | The handle in `channel` is not an active Storefront API sales channel in the workspace.  |
| `401`  | `sign in to continue`                                   | The `shopper-token` is missing or expired, or the shopper signed out.                    |
| `404`  | `cart not found`                                        | The cart token is missing, unknown or expired, or the cart has already been checked out. |
| `422`  | `only 2 of SCARF-BLUE available at this location`       | A rule stopped the request.                                                              |
| `429`  | `too many attempts, try again in 12 minutes`            | A shopper or the store reached a limit.                                                  |
| `503`  | `The service is briefly unavailable, please try again.` | A sign-in code email could not be queued, or a service was briefly unreachable.          |

## Rate limits

Two limits apply, and both answer with `429`.

* **Per request rate, on every endpoint.** Requests signed with a public key, or with no key, are limited to 10 a second from one IP address. Requests signed with a secret key are limited to 50 a second for each key, and 50 a second from one IP address. Short bursts above these rates are allowed. The response is `{"status": false, "message": "Too many requests"}`.
* **Per shopper and per store, on Storefront writes.** Requesting sign-in codes, signing in, creating a cart, checking out, looking up orders, reviewing, commenting, sending messages and subscribing are limited over a 15 minute window. The message says how long to wait.

If your server calls the Storefront API for many shoppers, sign the requests with a secret key and send each shopper's address in the `client-ip` header, so they are not counted as one shopper.