Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
401 unauthenticated on every call |
Token expired (1 h) or revoked; business disconnected the app | Refresh; if refresh says invalid_grant, ask the owner to reconnect |
404 for a business you can see in your system |
No active connection, or sandbox/live mismatch | Check Connected businesses in the console; check environments |
403 insufficient_scope |
Scope not requested, not approved, or not granted by this business | Request it; the business must re-authorise to grant new scopes |
403 on /accounts, /staff etc. |
Dashboard-only routes are not available to tokens | Use the documented integration endpoints |
422 No product is mapped to external variant … |
Order sent before product sync | Sync products first, or send POS variantId |
422 Payment … does not match the order total |
Your total and POS's differ (price drift, VAT basis, modifiers) | Send unitPrice per line as charged; check pricesIncludeTax |
Sync run PARTIAL |
One product failed (often a SKU or barcode already used) | See run.errors; fix and resend that product |
| Conflicts keep appearing | Business made a field POS-owned | Stop sending changes for it, or ask the business to change ownership |
| Webhook signature fails | Verifying parsed/re-serialised JSON; wrong secret; clock skew | Verify the raw body; use the endpoint's own secret; sync your clock (NTP) |
| Webhook endpoint disabled | 50 consecutive failures | Fix the endpoint, re-enable it, retry dead deliveries |
429 |
Over 300 requests/minute | Back off per retry-after; batch syncs (200 per call) |
Every response has x-request-id; the console's API requests tab lists your recent calls with status and error code.