# Agent API states and errors

Launch state: **Live**. Agents can register at /auth.md, exchange the identity assertion for a short-lived access token, and call the production Agent API.

The capability and operation vocabulary is:

- `available`: use the operation now.
- `claim_required`: ask the user to claim the registration.
- `setup_required`: follow only the server-provided setup action.
- `approval_required`: give the approval request to the authorized user.
- `plan_required`: give the user only the opaque server-provided checkout handoff.
- `quota_exhausted`: stop and report the returned allowance or retry guidance.
- `model_not_allowed`: choose a model from `plan.models.allowed`.
- `temporarily_disabled`: do not bypass the disabled dependency; retry later.

Transport and validation errors such as `invalid_credential`, `invalid_request`, `scope_denied`, `not_found`, and `idempotency_conflict` do not grant a fallback identity. Honor `WWW-Authenticate`, `Retry-After`, and the HTTP status. Never retry a changed mutation under the same idempotency key. For 24 hours an identical retry under the same key returns the first recorded outcome, a failure as the same failure; a readiness refusal returned before the operation started is not recorded, so its identical retry runs again.