What Do CLI Exit Codes and Errors Mean?

The Shovels CLI uses structured exit codes and JSON error messages to make troubleshooting straightforward for developers, scripts, and AI agents.

The CLI uses distinct exit codes for each error category. Scripts and AI agents can branch on the exit code without parsing the error message.

Exit Codes

Code	Type	Meaning
0	Success	Command completed successfully
1	Client error	Invalid flags, validation failure, or bad request
2	Auth error	Missing or invalid API key
3	Rate limited	Too many requests (HTTP 429)
4	Credits exhausted	API credit limit reached (HTTP 402)
5	Server/network error	Server failure or connectivity issue

Error Response Format

Errors are written to stderr as structured JSON:

{
  "error": "descriptive message explaining what went wrong",
  "code": 2,
  "error_type": "auth_error"
}

The error_type field provides a machine-readable classification:

error_type	Exit Code	Common Causes
client_error	1	Missing required flags, invalid flag values
validation_error	1	Invalid date range, bad geo_id format (HTTP 422)
auth_error	2	No API key configured, or key is invalid (HTTP 401)
rate_limited	3	Too many concurrent requests (HTTP 429)
credit_exhausted	4	Monthly credit limit reached (HTTP 402)
server_error	5	Shovels API returned a 5xx error
network_error	5	DNS failure, timeout, or connection refused

Common Errors and Solutions

Exit 1: Client Error

Missing required flags:

$ shovels permits search --geo-id 92024
Error: required flags "permit-from", "permit-to" not set

Fix: Add the required --permit-from and --permit-to flags.

Invalid date range:

{
  "error": "permit_from must be before permit_to",
  "code": 1,
  "error_type": "validation_error"
}

Fix: Ensure your --permit-from date is earlier than --permit-to. Use YYYY-MM-DD format.

Properties search validation:

properties search validates locally before making any API call, so these cost no credits:

Error	Cause
at least one of --geo-id or --legal-owner required	No scope given
--legal-owner values must not be empty	An empty string was passed to --legal-owner
maximum 10 --legal-owner values per request, got 11	More than 10 owners
invalid date format for --permit-from: "08-2026" (expected YYYY-MM-DD)	Malformed date
--property-min-lot-size must not be negative, got -5	Negative range bound
--property-min-year-built (2000) must not exceed --property-max-year-built (1990)	Inverted range pair
unknown flag: --permit-to	properties search has no upper date bound — use permits search

Auth is checked before local flag validation, so a missing API key surfaces as exit 2 even when your flags are also invalid. Fix the key first, then the flags.

Properties get ID errors:

An ID that is well-formed but has no property behind it is not an error — the row is omitted and the ID appears in meta.missing with exit 0. Two cases do fail the whole request with exit 1:

$ shovels properties get BJjCWAMtccQ NOT_A_REAL_ID
{"error":"...Could not decode property id 'NOT_A_REAL_ID' at position 2. Each id must be an ADDRESS geolocation id...","code":1,"error_type":"validation_error"}

$ shovels properties get RMjg6rIIh2k
{"error":"...Property id 'RMjg6rIIh2k' at position 0 is a city, county, or jurisdiction id, not an ADDRESS id...","code":1,"error_type":"validation_error"}

Fix: pass only address IDs, from a properties search row’s id or from addresses search. One bad ID takes down the entire batch, so validate before sending 50.

Exit 2: Auth Error

{
  "error": "API key is required. Set SHOVELS_API_KEY or run: shovels config set api-key YOUR_KEY",
  "code": 2,
  "error_type": "auth_error"
}

Fix: Set your API key via environment variable or config file. See CLI authentication.

Exit 3: Rate Limited

{
  "error": "rate limited after 3 retries",
  "code": 3,
  "error_type": "rate_limited"
}

The CLI automatically retries rate-limited requests with exponential backoff and jitter (up to 3 retries). If this error appears, wait a moment and try again, or contact support if it persists.

Use --no-retry to disable automatic retry if you want to handle rate limits yourself in a script.

Exit 4: Credits Exhausted

{
  "error": "credit limit reached",
  "code": 4,
  "error_type": "credit_exhausted"
}

Your monthly credit allowance is used up. Check your usage with shovels usage and contact [e-mail] to increase your limit.

Exit 5: Server or Network Error

{
  "error": "connection timeout after 30s",
  "code": 5,
  "error_type": "network_error"
}

Check your internet connection. If the Shovels API is down, try again later. You can adjust the timeout with --timeout 60s.

Using Exit Codes in Scripts

shovels permits search --geo-id 92024 \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  > results.json 2> error.json

case $? in
  0) echo "Success: $(jq '.meta.count' results.json) records" ;;
  2) echo "Auth failed — check your API key" ;;
  3) echo "Rate limited — retrying in 60s"; sleep 60 ;;
  4) echo "Out of credits — contact sales" ;;
  *) echo "Error: $(cat error.json)" ;;
esac

Related Articles

• CLI authentication — Configure your API key
• Querying properties from the CLI — Properties flags and ID rules
• API error handling — REST API error codes
• API credit limits — Understanding credit consumption