Agent Error Recovery

What each error code means and the recovery an agent should take.

Updated September 3, 20261 min readPostsale CLI

From AGENTS.md. On gated abort, use envelope data.gate and data.next.

`error.code`	Action
`auth_required`	`postsale auth login` or `POSTSALE_TOKEN`
`api_key_unsupported`	The active credential is an API key and this operation needs a login session (user profile, automations, templates, key/payment/subscription management). Not retryable on the key; surface to a human or skip (exit 100)
`api_key_rejected`	The API key was refused. If `error.missing_scopes` is present, the owner grants those permissions in the Postsale app (effective within about a minute); otherwise the key is unknown, revoked, disabled, or off-plan. Never "log in"; do not retry (exit 100)
`subscription_inactive`	Surface to human (billing)
`validation_failed`	Fix `error.details` fields
`rate_limited`	Wait `error.retry_after` seconds
`confirmation_required`	`gate=direct` → retry with `--yes`; `gate=swarm_size` → interactive TTY only
`swarm_authorization_required`	Batch gate: TTY approve or `POSTSALE_SWARM_AUTOAUTH=1`; reword read templates if keyword false positive
`user_denied` / `swarm_aborted_by_user`	Do not retry without new human instructions
`terms_acceptance_required`	Owner-action gate (`gate=owner_action`). `accept_channel=hosted_page` → relay `accept_url`; `in_app` (Shipsurance) → relay `remediation`. Owner-only; STOP, don't retry until confirmed (exit 78)
`subscription_reactivation_required`	Owner-action gate (`gate=owner_action`). Relay `reactivate_url` to the human owner; STOP, don't retry until reactivated (exit 101)
`account_creation_requires_human`	Owner-action: account creation / signup is browser-only, human-only. Cannot be done by the agent (exit 78)
`operation_not_in_v0_allowlist`	Check `error.safety_class`; allowlist refusal
`network_error`	Brief wait + retry
`request_timeout`	Retry or raise `POSTSALE_HTTP_TIMEOUT_MS`
`update_channel_closed`	The public release channel is not open yet; do not retry (exit 78)
`not_found`	Verify id with search first (exit 104)