Scopes and errors
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:
{ "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 |