# Error format

> The structured JSON error envelope Shoplazza CLI writes to stderr: its error types, fields, request ID, and how to handle them programmatically in scripts.

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

## Error envelope

```json
{
  "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

```shell
# 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:

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