Errors & exit codes

Exit codes

Code	Meaning	What to do
0	Success	Continue
2	Usage / budget / rate-limit / unavailable / failed run wait	Fix args, check frontpage usage, wait and retry
3	Conflict	CAS tip moved, active agent run, or cancel-while-deploying. See below
4	Authn / authz / many 404s	Check key, membership, and subdomain (404 often hides existence)
5	Unexpected server / network / API disabled	Retry; verify FRONTPAGE_API_BASE and that Public CLI is enabled

JSON error envelope

{
  "ok": false,
  "command": "push",
  "error": {
    "message": "…",
    "code": "conflict",
    "httpStatus": 409,
    "exitCode": 3
  }
}

With --json, failures still set the process exit code and print the envelope on stdout. Parse ok and error.exitCode; do not scrape human text.

CAS / push conflicts (exit 3)

frontpage status --json
frontpage pull
# re-apply local edits if pull overwrote them
frontpage push --message "…" --json

Active run conflicts (exit 3)

frontpage runs --json
frontpage runs wait
# or, if the user asked you to stop it:
frontpage runs cancel <runId>
frontpage push --message "…" --json

Auth / access (exit 4)

• Missing key → frontpage login or set FRONTPAGE_API_KEY
• 401 → recreate the key in the editor Developers panel
• 404 on site-scoped calls → wrong slug or no membership (existence may be hidden)
• 403 → member without privilege for that action (example: viewer running people add)

People-specific 400 / 409 messages (invalid phone, stolen email, hide vs forget) live on People CRM. A 404 Person not found. means that UUID is not on the claimed site, not that the slug is wrong (slug failures say Site not found.).

API disabled (exit 5)

If Public CLI is off for the environment, /api/v1/me may look like “not found.” The CLI mentions PUBLIC_CLI_ENABLED. That is an operator/config issue, not a bad local install.

Rate limits (exit 2)

HTTP 429 with error.code: "rate_limited" and a Retry-After header means you exhausted a request bucket. Not necessarily your AI plan budget. Full class table and command mapping: Rate limits.

frontpage pull --json
# if error.code === "rate_limited": sleep Retry-After seconds, then retry

frontpage usage
# if ai.atLimit / ai.over: plan budget, not HTTP throttle

Plan budget vs throttle

Signal	Meaning	Next step
rate_limited / 429	Request throttle	Honor Retry-After; see Rate limits
usage meters over / atLimit	Plan AI/bandwidth/storage	Analytics & usage; upgrade or wait for cycle reset

Doctor first

frontpage doctor --json
frontpage whoami --json
frontpage status --json