Errors | Papertracc Docs

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

{
  "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.
`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.

{
  "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.