错误处理
Shoplazza CLI 如何报告失败,以及如何在脚本与智能体中处理。
成功与错误信封
成功时,数据以 JSON 信封输出到 stdout:
json
{ "ok": true, "action": "products.list", "data": { } }
失败时,错误信封输出到 stderr:
json
{ "error": { "type": "api", "message": "Product not found", "hint": "Check the product ID and try again" }, "request_id": "req_abc123" }
务必读 hint——它告诉你下一步。保留 request_id 以便求助。完整结构见错误格式。
退出码
按退出码分支,而不是解析文本:
| 码 | 类型 | 常见处理 |
|---|---|---|
0 | 成功 | — |
1 | API 错误 | 检查响应体 / request_id |
2 | 校验错误 | 修正 flag 或输入 JSON |
3 | 认证错误 | shoplazza auth login |
4 | 网络错误 | 检查连通性,重试 |
5 | 内部错误 | 上报 bug |
shell
shoplazza products list
case $? in
0) echo "ok" ;;
3) shoplazza auth login --store-domain my-store.myshoplazza.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
重试
只重试瞬时失败(网络 4;部分 1 限流响应)。不要盲目重试校验(2)或认证(3)错误——先修因。在 CI 中限制重试次数并退避。