> ## 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. |
| `CONFIRMATION_REQUIRED` | 1 | The action needs an explicit human confirmation (e.g. launching a campaign assigned to someone other than its creator). | Re-run the command with `--yes` after confirming. |

***

## 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](https://www.landbase.com/docs/reference/exit-codes.md) — numeric exit codes
* [How to automate with scripts](https://www.landbase.com/docs/guides/how-to/automate-with-scripts.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.