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

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