Error format

Shoplazza CLI uses structured JSON error envelopes on stderr for consistent error handling.

Error envelope

{
  "error": {
    "type": "api",
    "message": "Product not found",
    "hint": "Check the product ID and try again"
  },
  "request_id": "req_abc123"
}

Error types

Type	Exit code	Description
api	1	Shoplazza API returned an error response
validation	2	Invalid CLI input (missing flags, bad format)
auth	3	Authentication failure (expired token, missing scope)
network	4	Network connectivity issue
internal	5	Unexpected CLI error

Fields

Field	Type	Description
error.type	string	One of the 5 error types above
error.message	string	Human-readable error description
error.hint	string	Actionable suggestion for resolving the error
request_id	string	Request ID for debugging (API errors only)

Handling errors programmatically

# Capture stderr for error details
output=$(shoplazza products get --id 999 2>&1)
exit_code=$?

if [ $exit_code -ne 0 ]; then
  echo "$output" | jq -r '.error.hint'
fi

stdout vs stderr

• stdout — Success data only (JSON envelopes with "ok": true)
• stderr — Errors, progress indicators, warnings, and hints

This separation ensures you can safely pipe stdout without corruption:

shoplazza products list --jq '.data.products[].id' | while read id; do
  shoplazza products get --id "$id"
done