> ## Documentation Index
> Fetch the complete documentation index at: https://www.landbase.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes

> Complete reference for landbase-cli error code strings — what each code means and how to handle it.

# Error codes

When landbase-cli encounters an error, it writes a JSON object to stderr with an `error.code` field. These codes are stable across versions and are safe to branch on in scripts.

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please wait before retrying.",
    "meta": { "retry_after_seconds": 30 }
  }
}
```

***

## Code reference

| Code               | Exit code | Meaning                                                                                                  | What to do                                                                 |
| ------------------ | --------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `AUTH_FAILED`      | 3         | No valid API key or session, or the credentials were rejected.                                           | Run `landbase-cli auth login`. Check `LANDBASE_API_KEY` in CI.             |
| `RATE_LIMITED`     | 2         | Too many requests in a short window.                                                                     | Wait and retry. Check `meta.retry_after_seconds` if present.               |
| `TIMEOUT`          | 4         | The request exceeded the configured timeout.                                                             | Retry, or increase `--timeout`. For long workflows, use `--wait`.          |
| `NETWORK_ERROR`    | 4         | A connectivity issue prevented the request from completing.                                              | Check your network and retry.                                              |
| `API_ERROR`        | 2         | The Landbase API returned an unexpected error.                                                           | Check `meta` for details. If the problem persists, contact support.        |
| `DOWNLOAD_FAILED`  | 2         | The file download could not be completed. The publish step may have failed, or the URL may have expired. | Re-run the publish workflow and retry.                                     |
| `INVALID_INPUT`    | 1         | The command received invalid arguments or flags.                                                         | Read `message` for the specific problem. Fix the command and re-run.       |
| `UPGRADE_REQUIRED` | 2         | The version of landbase-cli you are running is too old to use this API.                                  | Run `landbase-cli update`.                                                 |
| `UPDATE_FAILED`    | 2         | The self-update process could not download or install the new binary.                                    | Check your network and write permissions in the install directory.         |
| `NOT_FOUND`        | 2         | The requested resource (dataset, run, session) does not exist or has been deleted.                       | Verify the ID. Run `landbase-cli datasets list` to see available datasets. |
| `SETUP_FAILED`     | 1         | A setup or configuration step failed (e.g. config permissions write).                                    | Check file system permissions for `~/.claude/` or `~/.codex/`.             |
| `CONFLICT`         | 2         | A resource conflict prevented the operation (e.g. duplicate upload).                                     | Check for an existing dataset with the same name.                          |

***

## Capturing error codes in scripts

Capture stderr separately from stdout:

```bash theme={null}
# Capture stdout to a variable and stderr to a temp file
OUTPUT=$(landbase-cli datasets list 2>/tmp/lb-err.json)
if [ $? -ne 0 ]; then
  CODE=$(cat /tmp/lb-err.json | jq -r .error.code)
  case "$CODE" in
    "AUTH_FAILED") landbase-cli auth login ;;
    "RATE_LIMITED") sleep 30 ;;
    "NETWORK_ERROR") sleep 5 ;;
    *) echo "Unhandled error: $CODE"; exit 1 ;;
  esac
fi
```

***

## Related

* [exit codes reference](/docs/reference/exit-codes) — numeric exit codes
* [How to automate with scripts](/docs/how-to/automate-with-scripts)