# Output and exit codes

Exit codes, environment variables and JSON your scripts can rely on.

## Branch on the exit code

Use the number to choose your next action. Treat the message as an explanation for a person.

| Code | Name | Meaning | What to do |
| --- | --- | --- | --- |
| 0 | `OK` | Done. | Continue. |
| 1 | `ERROR` | Unexpected error, or an answer the CLI could not read. | Stop and report error.message to the person. Do not retry a write. |
| 2 | `USAGE` | Bad flags or arguments. | Fix the command. recala schema --json lists every flag. |
| 3 | `NOT_AUTHENTICATED` | Not signed in, or the credential was refused. | Stop and ask the person to run recala login. |
| 4 | `FORBIDDEN` | Your role does not allow it. | Stop and name what is missing. Never look for another way around it. |
| 5 | `NOT_FOUND` | Not found. | Check the id with a list command. |
| 6 | `CONFLICT` | Not allowed yet: no organization selected, not ready to schedule, or no person linked. | Fix the precondition the message names, or ask the person. |
| 7 | `INVALID` | The input was refused. | Read error.message and fix the input. |
| 8 | `RATE_LIMITED` | Rate limited. | Wait, then retry once. |
| 9 | `UNAVAILABLE` | Server or network trouble. | Retry a read once. After outcome_unknown, never retry: check the state first. |
| 10 | `CONFIRMATION_REQUIRED` | Confirmation is missing or was declined. | Nothing was sent. Ask the person to confirm in a terminal or grant this sign-in access. |
| 11 | `PAYMENT_REQUIRED` | Not allowed to spend: no credits, a cap reached or a blocked topic. | Stop and tell the person. An agent never buys. |

## Set defaults for a shell or agent

| Variable | What it does | Priority |
| --- | --- | --- |
| `RECALA_ORG` | Organization name, slug or id. | Below `--org`; above the saved organization. |
| `RECALA_JSON` | Set to 1 for JSON output. | Applies across commands in this shell. |
| `RECALA_API_KEY` | API key credential, where organization-key access is enabled. | Before RECALA_TOKEN and saved login. |
| `RECALA_TOKEN` | Access-token credential. | Before saved login. |
| `RECALA_API_URL` | Override the API address for a development environment. | Below `--api-url`. |

```
RECALA_ORG=rebeam RECALA_JSON=1 recala topics list
```

Do not put credentials in copied commands, logs or prompts. The [authentication table](https://recala.co/developers/cli/#authentication) explains which source is used.

## Read one JSON document

On success, stdout contains exactly one JSON document and the process exits 0. On failure, stdout is empty; the last line of stderr is a JSON object with an error key. Earlier stderr lines may be progress messages.

```
recala schema --json
```

| Error field | Meaning |
| --- | --- |
| `code` | A stable machine name, such as confirmation_required or outcome_unknown. |
| `message` | A sentence for a person. Do not parse it. |
| `status` | The HTTP status the API answered with, or null. |
| `exit_code` | The process exit code, repeated so a log line carries it. |
| `retryable` | True only for rate limits and server trouble, and never after outcome_unknown. |

Never retry a write with an unknown outcome. Read the resource’s state first. Next, follow the [AI agent guide](https://recala.co/developers/agents/) to put these rules into practice.