Error Codes

On failure, stdout holds:

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

Branch on code in code; message is for people.
For errors returned by the API, details.status is the HTTP status. When the server supplies its own error code it goes in details.serverCode, with extra information in details.serverDetails.
Exit codes: see Exit codes.

Authentication

code	Exit	Meaning	What to do
`no_api_key`	1	No API key found. Non-interactive environments (CI, agents, pipes) never start a sign-in	Run `tufty login`, set `TUFTY_API_KEY`, or `tufty auth set <key>`
`unauthorized`	1	The key is invalid or revoked (HTTP 401)	Get a new key on the API keys page
`forbidden`	1	Access denied (HTTP 403)	Check which account the key belongs to
`not_configured`	1	`tufty auth get` found no key	Sign in or save a key first
`login_expired`	1	The authorization request expired or was declined	Run `tufty login` again
`login_timeout`	1	Authorization wasn't completed within 30 minutes	Run `tufty login` again

code	Exit	Meaning	What to do
`insufficient_balance`	1	Not enough credits (HTTP 402). `details.required` is what this step needs; stderr also prints the top-up link	Top up under Account settings → Credits, then run again

code	Exit	Meaning	What to do
`invalid_request`	1	The server rejected the request (HTTP 400). `details.serverCode` gives the reason, e.g. `unknown_template`, `reference_not_allowed`	Check the inputs; `tufty tools describe <id>` shows the current options
`not_found`	1	Not found (HTTP 404), usually a mistyped `runId`	Check the `runId`
`cli_version_too_low`	1	The CLI is older than the server supports (HTTP 426)	Run `npm install -g @tufty/cli@latest`
`server_error`	1	Server error (HTTP 5xx), or a response that couldn't be parsed	Retry later
`http_error`	1	Any other unsuccessful HTTP status	Check `details.status` and retry later
`network_error`	1	Couldn't reach the server; `details.url` is the request URL	Check the network, proxy or `--base-url`
`manifest_unavailable`	1	Couldn't load the tool manifest, and there's no local cache	Check the network and retry

All of these exit with code 2.

code	Meaning	What to do
`usage_error`	Invalid arguments: unknown option, value not among the choices, missing option value, non-positive `--timeout`, and so on. Errors from argument parsing carry `details.commanderCode`	Check `tufty <tool> -h`
`unknown_command`	No such command; `details.suggestions` lists close matches	Fix the command name
`tool_not_found`	No tool with that id for `tufty tools describe`; `details.availableTools` lists them all	Fix the tool id
`missing_input`	Fewer inputs than the tool needs; `details` has `flag`, `min`, `got`	Add the missing inputs
`too_many_inputs`	More inputs than allowed, or more than 4 images joined with `+` for one product	Pass fewer inputs
`too_many_images`	Products × models × `--count` exceeds 16; `details` has `pairs`, `count`, `max`	Split into several runs or lower `--count`
`file_not_found`	A local file doesn't exist; `details.path` is the path	Check the path
`invalid_video`	The video is truncated or missing its `moov` index; `details.filename` is the file	Re-export or re-download the video
`invalid_input`	A malformed `data:` URL	Check the `data:` URL

code	Exit	Meaning	What to do
`task_failed`	1	Generation failed on the server; `details` has `runId`, `tool`, `serverCode`	Retry, or try different input images or `--notes`
`timeout`	1	Not finished within `--timeout`; `details.runId` is the run. The run isn't cancelled	Run `tufty status <runId> --wait`

code	Exit	Meaning	What to do
`upload_failed`	1	Uploading to storage failed	Retry later
`download_failed`	1	Downloading an input URL, or an output for `--save`, failed after 3 attempts; `details.url` is the URL	Check the URL or network and retry
`internal_error`	1	Something unexpected went wrong	Retry with `--verbose` and send us the output