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:
{ "ok": true, "data": { } }
On failure, an error envelope goes to stderr:
{ "ok": false, "error": { "type": "api", "message": "Product not found", "detail": { "status_code": 404, "request_id": "req_abc123" } } }
At an interactive terminal with pretty or table output, the same error prints as a readable Error: line (with Hint: and Request ID: lines when present) instead. Piped or redirected stderr, and any json, ndjson, or csv output (json is the default when piped, in CI, or with --no-input), always get the JSON envelope.
Read the hint when present — it tells you the next action. Keep error.detail.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 error.message / error.detail.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 |
130 | Canceled | A prompt or confirmation was declined at a terminal — nothing to fix |
shoplazza products list
case $? in
0) echo "ok" ;;
3) shoplazza auth login --store-domain my-store.myshoplaza.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:
shoplazza discounts +percent-code --target order --percent 20 --code SAVE20 --dry-run
At an interactive terminal, destructive commands (deletes, cancels, orders +refund, products +unpublish, themes push, …) also ask you to confirm before the write goes out. Scripts, CI, agents, and --dry-run are never prompted.
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.