# 错误格式

> Shoplazza CLI 写入 stderr 的结构化 JSON 错误结构：错误类型、字段、请求 ID，以及脚本中的程序化处理方式。

Shoplazza CLI 在 stderr 上使用结构化 JSON 错误结构。

## 错误结构

```json
{
  "error": {
    "type": "api",
    "message": "Product not found",
    "hint": "检查商品 ID 后重试"
  },
  "request_id": "req_abc123"
}
```

## 错误类型

| 类型 | 退出码 | 说明 |
|------|--------|------|
| `api` | 1 | Shoplazza API 返回错误响应 |
| `validation` | 2 | CLI 输入无效（缺少参数、格式错误） |
| `auth` | 3 | 认证失败（令牌过期、作用域不足） |
| `network` | 4 | 网络连接问题 |
| `internal` | 5 | 非预期的 CLI 错误 |

## 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `error.type` | string | 上述 5 种错误类型之一 |
| `error.message` | string | 人类可读的错误描述 |
| `error.hint` | string | 可执行的解决建议 |
| `request_id` | string | 请求 ID，用于调试（仅 API 错误） |

## stdout vs stderr

* **stdout** — 仅成功数据（`"ok": true` 的 JSON 信封）
* **stderr** — 错误、进度指示器、警告和提示

这种分离确保 stdout 可安全管道传输：

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