# Exit codes and errors

> The exit codes div returns, where it writes output, and the API error codes it reports with the fix for each.

## Exit codes

| Code | Meaning |
| --- | --- |
| the run's exit code | `div run`, `div eval run` and `div logs` for a finished run that exited non-zero. A run that exits 3 makes `div run` exit 3. |
| `0` | Success. Also returned when you detach from a run, and by `div stop` for a run that had already finished. |
| `1` | The API rejected the request or could not be reached, or a run stopped without an exit code (spend limit, usage limit, canceled). |
| `2` | Invalid command, flag or argument, or no API key. |
| `130` | [`div agent prompt`](https://docs.divergentlabs.xyz/sandboxes/cli/agent.md#prompt): the agent's turn was interrupted, or you pressed Ctrl-C. The turn continues after Ctrl-C. |

A missed [check](https://docs.divergentlabs.xyz/compute/cli/run.md#check-syntax) does not change the exit code. [`div result`](https://docs.divergentlabs.xyz/compute/cli/result.md) exits `1` when there is no result to print.

## Output streams

| Stream | Content |
| --- | --- |
| stdout | The run's own stdout, and command results such as run names, rows and JSON. |
| stderr | The run's own stderr, and every message from `div` itself: progress, summaries, warnings and errors. |

Colour is off when stdout is not a terminal. When it is on, green means running, red means failed, yellow means the run reached its spend limit, and grey means finished.

## Usage errors

An invalid command exits `2` and names the flag or value that is wrong. Unknown flags are errors, not ignored. Run `div <command> --help` for the command's flags.

## API errors

When the API rejects a request, `div` prints `error: ` followed by the API's message and exits `1`. The message says what is wrong and what to do. For a few codes, `div` prints a second line with another option, marked in the last column.

| Error code | HTTP status | What to do | Extra line from `div` |
| --- | --- | --- | --- |
| `unauthorized` | 401 | Run `div login`. | Set `DIVERGENT_API_KEY` to a valid key instead. Keys start with `dv_live_`. |
| `insufficient_credit` | 402 | Top up on the **Billing** page in the dashboard. | |
| `usage_limit_reached` | 402 | Raise the usage limit on the **Billing** page in the dashboard. | |
| `card_declined` | 402 | Update the card on the **Billing** page in the dashboard. | A link to [app.divergentlabs.xyz/billing](https://app.divergentlabs.xyz/billing). |
| `insufficient_scope` | 403 | Run `div login` for a key with every scope. | For `sandboxes:` and `secrets:` scopes: add both scopes to the key under **Settings** instead. |
| `not_found` | 404 | Check the name. | |
| `secret_not_found` | 404 | Run `div secrets --environment <env>` to list the environment's secrets. | |
| `unknown_environment` | 404 | Create the environment with `div secrets env add`, or list environments with `div secrets env ls`. | |
| `conversation_not_found` | 404 | Run `div agent conversations` to list the sandbox's conversations. | |
| `not_running` | 409 | Resume the sandbox with `div sandbox resume`. | |
| `agent_unavailable` | 409 | The sandbox was created before agents were available. Create a new sandbox with `div sandbox create`. | |
| `too_many_turns` | 409 | Wait for a conversation to finish, or create a larger sandbox with `div sandbox create --size`. | |
| `harness_mismatch` | 409 | Leave out `--harness`, or start a new conversation with `--new`. | |
| `quota_exceeded` | 409 | GPU limit reached. Stop a run with `div stop`, or wait for one to finish. | |
| `container_quota_exceeded` | 409 | Container limit reached. Stop a run with `div stop`, or pause an endpoint. | |
| `storage_full` | 409 | Storage limit reached. Delete files on the **Storage** page in the dashboard. | |
| `sandbox_quota_exceeded` | 409 | vCPU limit for running sandboxes reached. Stop a sandbox with `div sandbox stop`. | Below Team: a link to [app.divergentlabs.xyz/plan](https://app.divergentlabs.xyz/plan). |
| `environment_in_use` | 409 | Delete the sandboxes the message names with `div sandbox rm`, then delete the environment. | |
| `default_environment` | 409 | The `default` environment cannot be deleted. Delete its secrets one at a time with `div secrets rm`. | |
| `sandbox_limit` | 409 | Sandbox limit reached. Delete a sandbox with `div sandbox rm`. | Below Team: a link to the plans. |
| `already_measured` | 409 | Pass `--again` to measure the version again. Without it, `div eval run` prints the earlier value and exits `0`, or follows the run still measuring the version. | |
| `unknown_sku` | 422 | Pick a `--gpu` value from `div catalog`. | The valid values. |
| `credentials_missing` | 422 | Create a sandbox with `--secret ANTHROPIC_API_KEY`, or sign in with `div sandbox ssh`. See [Give the agent credentials](https://docs.divergentlabs.xyz/sandboxes/agents.md#give-the-agent-credentials). | |
| `unknown_secrets` | 422 | Set the secret in the sandbox's environment with `div secrets set <name> --environment <env>`, or let sandboxes receive it with `div secrets products <name> runs,sandboxes --environment <env>`. | |
| `unknown_harness` | 422 | Use `--harness claude` or `--harness opencode`. | |
| `no_weights` | 422 | Upload the model files with `div storage put`, or check the path with `div storage ls`. | |
| `validation_failed` | 422 | Fix the fields listed below the message, one per line. | |
| `supplier_unreachable` | 502 | Retry in a minute. | |
| any other 5xx | 5xx | Retry. | Check `div runs` before you retry a `div run`, because the run may have started. |

To raise a compute limit, or a sandbox limit on Team, contact us.

When the API cannot be reached, `div` prints the URL it tried and exits `1`. Run `div whoami` to see which URL is configured and where it came from. [`div papers`](https://docs.divergentlabs.xyz/compute/cli/papers.md) contacts arXiv instead of the API.

For plan limits, see [`div limits`](https://docs.divergentlabs.xyz/compute/cli/limits.md#compute-limits).

## Help

```bash
div --help           # list commands
div run --help       # flags for one command
div --version
```

`div` with no command prints the command list and exits `1`.
