Error Catalog

Canonical error categories for API and broker workflows. Use this table to drive retry policy, user-facing error messaging, and escalation runbooks.

Code	When It Happens	Remediation
invalid_argument	Input schema or required fields are invalid.	Validate payload shape and required fields before sending.
unauthenticated	Token missing, expired, or sender-proof verification failed.	Refresh short-lived token and regenerate DPoP/mTLS proof.
permission_denied	Caller is not authorized for the requested operation.	Verify caller identity, permissions, and target resource access.
failed_precondition	State transition is invalid (replayed bootstrap, exhausted/revoked lease).	Start a new lease/bootstrap sequence and avoid replayed artifacts.
not_found	Requested lease, challenge, or target resource cannot be found.	Check identifiers and ensure tenant/principal match.
internal	Unexpected server-side failure.	Retry with backoff; if persistent, escalate with request ID + timestamp.

Operational Guidance

Always log request ID, tenant ID, principal ID, and endpoint path for debugging.
Do not retry `permission_denied` blindly; fix authorization first.
Treat repeated `unauthenticated` proof failures as possible key compromise signal.