跳到主要内容

错误处理

Shoplazza CLI 如何报告失败,以及如何在脚本与智能体中处理。

成功与错误信封​

成功时,数据以 JSON 信封输出到 stdout:

json
{ "ok": true, "data": { } }

失败时,错误信封输出到 stderr:

json
{ "ok": false, "error": { "type": "api", "message": "Product not found", "detail": { "status_code": 404, "request_id": "req_abc123" } } }

在交互式终端中使用 pretty 或 table 输出时,同一错误改为显示易读的 Error: 行(有则附带 Hint: 与 Request ID: 行)。stderr 被管道或重定向,以及 json、ndjson、csv 输出(管道、CI 或 --no-input 下默认就是 json)时,始终输出 JSON 信封。

有 hint 时务必读——它告诉你下一步。保留 error.detail.request_id 以便求助。完整结构见错误格式。

退出码​

按退出码分支,而不是解析文本:

码类型常见处理
0成功—
1API 错误检查 error.message / error.detail.request_id
2校验错误修正 flag 或输入 JSON
3认证错误shoplazza auth login
4网络错误检查连通性,重试
5内部错误上报 bug
130已取消在终端中拒绝了提示或确认——无需处理
shell
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

完整表见退出码。

写操作前先预览​

任何写操作,执行前用 --dry-run 预览请求:

shell
shoplazza discounts +percent-code --target order --percent 20 --code SAVE20 --dry-run

在交互式终端中,破坏性命令(删除、取消、orders +refund、products +unpublish、themes push 等)发出写请求前还会请你确认。脚本、CI、智能体和 --dry-run 不会被提示。

重试​

只重试瞬时失败(网络 4;部分 1 限流响应)。不要盲目重试校验(2)或认证(3)错误——先修因。在 CI 中限制重试次数并退避。

参见​

在此页面