Going live
Limits and errors
The limits every integration works within, and what each error means.
Limits
| Limit | Value |
|---|---|
| Rate | 600 requests a minute per shop key; 120 a minute per partner key. Over that you get 429 with Retry-After. Batch your writes. |
| Batch size | 200 products per /products/batch or snapshot call; 500 items per /inventory call. |
| Variations | Up to 100 variants and 3 options per product. |
| Values | TZS only. Price 0 to 100 000 000; stock −100 000 000 to 100 000 000 (stored as 0 when negative). A row outside these is rejected on its own. |
Idempotency
Send an Idempotency-Key header (any unique string, such as a UUID) on writes you might retry. The same key within 24 hours replays the first response instead of doing the work again, and the replay carries Idempotent-Replay: true.
HTTP errors
Errors come back as {"error": {"code": "…", "message": "…"}}. Branch on code; show message to people. Every failed call is also listed in the console's error log for 14 days.
| HTTP | error.code | Meaning |
|---|---|---|
| 401 | invalid_key | Missing, wrong or revoked key, or the wrong kind of key for this endpoint. |
| 402 | feature_not_in_plan | The shop's plan doesn't include POS sync. |
| 403 | connection_paused | The shop paused the link. |
| 403 | vendor_pending | Your account is waiting for approval; until then a partner key works for the sandbox only. |
| 403 | vendor_suspended | Your partner account is suspended. |
| 403 | not_sandbox | Sandbox tools need a sandbox key. |
| 404 | unknown_order, unknown_snapshot, unknown_code | It isn't yours, or doesn't exist. |
| 409 | snapshot_closed, already_accepted, … | Already finished, or already answered differently. |
| 422 | too_many_removed, no_products, validation | Fix the request. A batch's own problems come back per product instead. |
| 429 | rate_limited | Slow down and honour Retry-After. |
Per-item errors
Problems with single products arrive inside a 200 batch response as status: "rejected" with human-readable errors. For inventory items, the codes are:
| Code | Means |
|---|---|
unknown_product | We have no product with that external_id. Send the full product first. |
unknown_variant | We have no such variation. Send the full product, with its variants, first. |
product_has_variants | A product with variations takes price and stock from them. Send variant_external_id. |