Errors & limits

HTTP status codes

Code	Meaning	What to do
`200`	Success
`400`	Bad request: missing parameter or wrong data type	Fix the request using `message`
`403`	Wrong API key, or not allowed to perform this action	Check the key and permissions; do not retry unchanged
`404`	Shop or record not found	Check the IDs in the path
`422`	Data fails business validation	Fix the data using `message`
`429`	Rate limit reached (code `106`) or too many wrong keys (code `109`)	Wait, then retry (see below)
`500`, `502`, `503`, `504`	Server error or temporary overload	Retry later with increasing waits

Errors return JSON with success: false:

JSON

{
  "success": false,
  "message": "You have reached the limit of requests",
  "error_code": 106
}

Field	Meaning
`success`	Always `false` for errors
`message`	Human-readable description; wording may change over time
`error_code`	Numeric error code, when provided. Handle errors in code with this field, not with `message`
`error`	Stable error name, when provided
`message_code`	POS business message code, when provided
`permission`	The missing permission when access is denied, when provided

Common error codes:

`error_code`	HTTP	Meaning
`105`	403	Invalid `api_key`
`106`	429	Rate limit reached
`109`	429	Too many wrong `api_key` attempts, locked for 5 minutes

Limits apply per endpoint (record IDs in the path do not count separately) and per:

Request type	Limit
Reads (`GET`)	Under 30 requests per second
Writes (`POST`, `PUT`, `DELETE`)	Under 100 requests per second
`GET /shops/{SHOP_ID}/inventory_histories`	3 requests per second

Going over returns 429 with error_code 106.

429 and 5xx: wait and retry with increasing delays (for example 1, 2, 4, 8 seconds) and stop after a few attempts. Honour the Retry-After header when present.
Other 4xx: fix the request; sending it again unchanged fails again.
A write (POST) that failed with a network error or timeout: check whether the record was created before sending it again, to avoid duplicates.
Large syncs: run sequentially or with few parallel workers, and prefer a large page_size over many small requests.