---
title: Exit codes
description: What each invideo CLI exit code means, what to do about it, and how --wait and --timeout retry and stop.
---
Every invideo CLI command ends with an exit code. Zero means it worked. Any other code says what went wrong and what to do next. The list comes from the CLI itself:

```bash
invideo help exit-codes
```

## Codes

Read the exit code first, then the message. A refused command prints one line to stderr in plain words, even with `--json`; `--json` shapes the answer on stdout, not the error. Scripts branch on the exit code.

| Code | Meaning | Fix |
| --- | --- | --- |
| `0` | It worked. | Nothing to do. |
| `1` | It failed, on invideo's side or for an unknown reason. | Read the `message`. If it fails again, file it with `invideo feedback bug`. |
| `2` | Usage error, or a request that cannot be done as asked. | Fix the command. Check its flags with `--help`. |
| `3` | Conflict: the timeline changed since your read. Read it again. | Run `invideo edit show` again for a new state token, and rebuild the change. |
| `4` | Not signed in: run `invideo auth login`. | Run `invideo auth login`. |
| `5` | A limit: credits or quota. | Stop, and tell the person. |
| `6` | Held by moderation: a safety review, not a refusal. | Wait, then run `invideo status <url> --wait` again. Do not resend. If it ends `failed`, change the input the review flagged. |
| `7` | Transient: nothing ran. | Run the same command again. |
| `8` | Needs the person's confirmation. | Stop, and ask the person to confirm it in invideo. |
| `9` | Update required. | Run `invideo update`, then run the command again. |

## How --wait and --timeout work with the codes

A command that starts something (a generation, an export or an upload) returns the URL to follow at once. It does not wait for the job unless you ask.

- **`--wait` follows a job.** `invideo status <url> --wait` checks back until the job is over. It follows jobs in any of your projects.
- **`--wait` retries code 7.** With `--wait`, any command tries again when nothing ran. A retry is the same request, so it never starts anything twice.
- **`--timeout` stops the wait.** `--timeout <s>` stops waiting after that many seconds. The job goes on in invideo; run `invideo status <url> --wait` later to pick it up.

```bash
invideo status <sequence-url> <thread-url> --wait --timeout 600
```

The command that started the job returns `<sequence-url>` and `<thread-url>`. `invideo status` follows jobs and saves nothing. To save a file, run `invideo notebook show <sequence-url> --out <dir>` after the job is over.

## Mistakes to avoid

These are the mistakes agents make with exit codes, and what to do instead.

| Avoid | Instead |
| --- | --- |
| Running a paid command again after a timeout to check on it. | Run `invideo status <url> --wait` on the URL it gave. |
| Sending the same `edit change` again after code 3. | Read the edit again with `invideo edit show`, and rebuild the change on the new token. |
| Asking the person for a password or a code after code 4. | Run `invideo auth login`. With no browser, run it with `INVIDEO_NO_BROWSER=1`. |
| Raising `--max-credits` on your own after code 5. | Stop, and tell the person the price. |

## Related

- [CLI commands and flags](/reference/cli)
- [Environment variables](/reference/environment)
- [MCP tools](/reference/mcp-tools)
- [Run invideo in CI and on servers](/how-to/ci-and-servers)