---
title: Scopes and errors
description: The partner API's scopes, and the shape and meaning of its errors.
---

## Scopes

A token needs at least one read scope (`inventory:read` or `purchase-boosts:read`). A token with neither is refused everywhere.

| Scope                  | Endpoints                                                                    |
| ---------------------- | ---------------------------------------------------------------------------- |
| `purchase-boosts:read` | `/purchase-boosts`                                                           |
| `inventory:read`       | `/inventory/*` (reads), `/cards`, `/webhook`                                 |
| `inventory:write`      | Holds and shipping (`/inventory/holds*`). Also needs `inventory:read`        |
| `inventory:move`       | Shelf moves, transfers between sites, take-outs. Also needs `inventory:read` |
| Either read scope      | `/connection`                                                                |

The shop chooses the scopes when registering your app. Asking for a scope it didn't allow fails with `invalid_scope` at authorization.

## Error shape

Errors look like `{ "error": "code" }`. A missing scope is named alongside:

```json
{ "error": "insufficient_scope", "scope": "inventory:read" }
```

The `WWW-Authenticate` header then also names the missing scope and the protected resource metadata URL.

## Common errors

| Status | `error`              | Meaning and fix                                                                            |
| ------ | -------------------- | ------------------------------------------------------------------------------------------ |
| 400    | `invalid_request`    | A parameter is invalid                                                                     |
| 401    | `invalid_token`      | The token is missing, expired, or for another resource. Refresh and retry                  |
| 403    | `insufficient_scope` | The token lacks a needed scope. Ask the shop to allow it, then authorize again             |
| 403    | `connection_revoked` | There is no connection, or the shop revoked it. Call `POST /connection` or authorize again |
| 403    | `client_disabled`    | The shop or Toreca Cloud paused the app                                                    |
| 403    | `forbidden`          | The approving member left or lost a needed permission. Have another member authorize       |
| 404    | `not_found`          | Nothing there, or the ID in the path is malformed                                          |
| 503    | `photo_unavailable`  | The unit's photo isn't available right now. Retry later                                    |