Error handling
How Shoplazza CLI reports failures, and how to handle them in scripts and agents.
Success and error envelopes
On success, data goes to stdout as a JSON envelope:
json
{ "ok": true, "action": "products.list", "data": { } }
On failure, an error envelope goes to stderr:
json
{ "error": { "type": "api", "message": "Product not found", "hint": "Check the product ID and try again" }, "request_id": "req_abc123" }
Always read the hint — it tells you the next action. Keep the request_id for support. See Error format for the full structure.
Exit codes
Branch on the exit code rather than parsing text:
| Code | Type | Typical fix |
|---|---|---|
0 | Success | — |
1 | API error | Inspect the response body / request_id |
2 | Validation error | Fix flags or input JSON |
3 | Authentication error | shoplazza auth login |
4 | Network error | Check connectivity, retry |
5 | Internal error | Report a bug |
shell
shoplazza products list
case $? in
0) echo "ok" ;;
3) shoplazza auth login --store-domain my-store.myshoplazza.com --domain products ;;
4) echo "network — retrying"; sleep 2; shoplazza products list ;;
*) echo "failed (code $?)" ;;
esac
See the full table in Exit codes.
Preview before writing
For any write, preview the request with --dry-run before executing:
shell
shoplazza discounts +percent-code --target order --percent 20 --code SAVE20 --dry-run
Retries
Retry only transient failures (network, 4; some 1 rate-limit responses). Do not blindly retry validation (2) or auth (3) errors — fix the cause first. In CI, cap retries and back off.