错误码

失败时标准输出是：

{ "ok": false, "code": "...", "message": "...", "details": { } }

程序判断请用 code；message 用来展示给人看。
接口返回的错误，details.status 是 HTTP 状态码；服务端给出了自己的错误码时放在 details.serverCode，附加信息在 details.serverDetails。
退出码见退出码。

认证

code	退出码	含义	处理
`no_api_key`	1	没有找到 API 密钥。非交互环境（CI、智能体、管道）不会弹出登录	运行 `tufty login`，或设置 `TUFTY_API_KEY`，或 `tufty auth set <key>`
`unauthorized`	1	密钥无效或已吊销（HTTP 401）	到 API 密钥页换一个密钥
`forbidden`	1	没有访问权限（HTTP 403）	确认密钥所属账户
`not_configured`	1	`tufty auth get` 时没有设置密钥	先登录或保存密钥
`login_expired`	1	授权请求已过期或被拒绝	重新运行 `tufty login`
`login_timeout`	1	30 分钟内没有完成授权	重新运行 `tufty login`

code	退出码	含义	处理
`insufficient_balance`	1	积分不足（HTTP 402）。`details.required` 是这一步需要的积分；标准错误里同时打印充值地址	到账户设置 → 积分充值后重新运行

code	退出码	含义	处理
`invalid_request`	1	服务端拒绝了请求（HTTP 400）。`details.serverCode` 是具体原因，例如 `unknown_template`、`reference_not_allowed`	检查输入；`tufty tools describe <id>` 查看当前选项
`not_found`	1	资源不存在（HTTP 404），常见于 `runId` 写错	检查 `runId`
`cli_version_too_low`	1	CLI 版本低于服务端要求（HTTP 426）	运行 `npm install -g @tufty/cli@latest`
`server_error`	1	服务端错误（HTTP 5xx），或响应无法解析	稍后重试
`http_error`	1	其他非成功的 HTTP 状态	查看 `details.status`，稍后重试
`network_error`	1	连不上服务端，`details.url` 是请求地址	检查网络、代理或 `--base-url`
`manifest_unavailable`	1	拉取不到工具清单，本地也没有缓存	检查网络后重试

这些错误的退出码都是 2。

code	含义	处理
`usage_error`	参数不合法：未知选项、取值不在可选范围内、缺少参数值、`--timeout` 不是正数等。参数解析阶段的错误带 `details.commanderCode`	运行 `tufty <tool> -h` 查看正确用法
`unknown_command`	命令不存在，`details.suggestions` 是相近的命令	修正命令名
`tool_not_found`	`tufty tools describe` 的 id 不存在，`details.availableTools` 是全部工具 id	修正工具 id
`missing_input`	输入数量少于工具要求，`details` 中有 `flag`、`min`、`got`	补齐输入
`too_many_inputs`	输入数量超过上限，或一件商品用 `+` 连接了超过 4 张图	减少输入
`too_many_images`	商品件数 × 模特图数 × `--count` 超过 16，`details` 中有 `pairs`、`count`、`max`	拆成多次运行，或调低 `--count`
`file_not_found`	本地文件不存在，`details.path` 是该路径	检查路径
`invalid_video`	视频文件被截断或缺少 `moov` 索引，`details.filename` 是文件名	重新导出或下载完整视频
`invalid_input`	`data:` URL 格式不正确	检查 `data:` URL

code	退出码	含义	处理
`task_failed`	1	服务端生成失败，`details` 中有 `runId`、`tool`、`serverCode`	重试，或更换输入图片、调整 `--notes`
`timeout`	1	在 `--timeout` 内没有完成，`details.runId` 是任务 id；任务不会被取消	运行 `tufty status <runId> --wait`

code	退出码	含义	处理
`upload_failed`	1	上传到存储失败	稍后重试
`download_failed`	1	下载外链图片，或 `--save` 下载成品失败（已重试 3 次），`details.url` 是地址	检查地址或网络后重试
`internal_error`	1	未预料的错误	加 `--verbose` 重试，并把输出反馈给我们