跳到主要内容

错误格式

Shoplazza CLI 在 stderr 上使用结构化 JSON 错误结构。只要 stderr 不是终端（被管道、重定向或被脚本捕获），或输出格式为 json、ndjson、csv，就输出该结构。在交互式终端中使用 pretty 或 table 输出时，同一错误会显示为易读的 Error: 行，并按需附带 Code:、Hint:、Request: 和 Request ID: 行。

错误结构​

API 错误：

json
{
  "ok": false,
  "error": {
    "type": "api",
    "message": "Product not found",
    "detail": {
      "status_code": 404,
      "request_id": "req_abc123",
      "method": "GET",
      "path": "/openapi/2026-01/products/999"
    }
  }
}

用法错误：

json
{
  "ok": false,
  "error": {
    "type": "validation",
    "subtype": "unknown_flag",
    "message": "unknown flag: --bogus",
    "hint": "run the command with --help to list valid flags"
  }
}

错误类型​

类型退出码说明
api1Shoplazza API 返回错误响应（403 以外的 4xx，或 5xx）
validation2CLI 输入无效（参数未知或缺失、格式错误）
auth3认证失败（令牌过期、作用域不足、HTTP 403）
network4网络连接问题
internal5非预期的 CLI 错误

取消提示时以 130 退出，不输出错误结构。

字段说明​

字段类型说明
okboolean恒为 false
error.typestring上述 5 种错误类型之一
error.subtypestring用法错误的稳定标识：unknown_command、unknown_flag、missing_required_flag、invalid_flag_value、invalid_argument 或 usage_error（有则返回）
error.codestringAPI 返回的业务错误码（有则返回）
error.paramstring出错的参数名（已知时返回）
error.messagestring人类可读的错误描述
error.hintstring可执行的解决建议（有则返回）
error.detail.status_codenumberHTTP 状态码（仅 API 错误）
error.detail.request_idstring请求 ID，用于调试（仅 API 错误）
error.detail.method、error.detail.pathstring出错的请求（仅 API 错误）

部分命令会在 error 对象中附加该命令特有的字段。

stdout vs stderr​

  • stdout — 仅成功数据（"ok": true 的 JSON 信封；--dry-run 预览和 auth status 等本地命令直接输出对象，不带信封）
  • stderr — 错误、进度指示器、警告和提示

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

shell
shoplazza products list --jq '.data.products[].id' | while read id; do
  shoplazza products get --params "{\"product_id\":\"$id\"}"
done
在此页面