Developer docs contents
Errors and request ids
Every error code, what it means and what to do.
Errors always have the same shape. error is written for a person; code is for your code to act on.
{
"error": "This key is limited to 50 requests a second.",
"code": "rate_limited",
"requestId": "req_7xV3f0yT8Qe1kz2bN4mH6A",
"retryAfterMs": 183
}| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request | Fix the products listed in problems (by index in your array) and resend. Nothing was queued. |
| 400 | invalid_json | The body is not valid JSON. |
| 401 | invalid_api_key | The key is missing, malformed, unknown or revoked. |
| 404 | store_not_found | No such store on your company. List them with GET /v1/stores. |
| 404 | product_not_found | No such product in that store. |
| 404 | batch_not_found | No such batch, or it is older than 24 hours. |
| 413 | too_large | The body is over 2 MB. Send fewer products per request. |
| 429 | rate_limited | Wait Retry-After seconds and resend. |
| 503 | unavailable | Briefly unable to accept writes. Retry with backoff. |
| 503 | backlogged | Writes are backing up. Retry in a few seconds. |
| 500 | internal_error | Our fault. Retry; if it persists, contact support with the request id. |
Per-product outcomes in a batch use their own codes: needs_name (a new code was sent without a name), full (the store already holds 20,000 products), reserved and invalid.
Request ids
Every response carries an X-Request-Id header, and every error repeats it as requestId. Log it next to your own records. When you contact support, quote it: it points us at the exact request. You can look one up yourself on the POS API page of the dashboard.
You can send your own X-Request-Id (8 to 64 letters, digits, _ or -). We use it instead of making one, so your logs and ours share the same id.