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.

{
  "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:

# 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

exit codes reference — numeric exit codes
How to automate with scripts

Get Started

Tutorials

How-to Guides

Capabilities

Explanation

Resources

Support

Error codes

Error codes

Code reference

Capturing error codes in scripts

​Error codes

​Code reference

​Capturing error codes in scripts

​Related

Error codes

Code reference

Capturing error codes in scripts

Related