Failure modes and recovery

This page defines every reason code in verdict schema version 1 and the builder response for each one.

Decision states

These reason codes describe a successful or unfinished evaluation rather than a policy failure.

If a client receives an unknown reason code, preserve the value and humanReason for diagnostics, but do not treat it as approval. Branch on outcome, and require the complete approved/allowed invariant before continuing.

Cross-cutting failures

Cross-cutting failures may be returned with checks: [] because they happen before a single policy check can explain the result.

Per-check failures

For these codes, the top-level reasonCode normally matches a failed item in checks[]. More than one check can fail; the top-level code is the primary failure, not the complete result.

Any data-dependent check can fail with code: "data_unavailable" instead of its policy-violation code. Read only the returned checks as evaluated: not_checked is not passed, and an absent check did not necessarily run. For a multi-leg action, legIndex identifies the zero-based decoded leg when the field is present.

Degraded and stale data

A degraded result is terminal for that verification request: outcome: "rejected" and reasonCode: "data_unavailable". It is not another form of pending, and a cached row is not evidence that the dependency met the check's freshness bound.

This abridged verdict shows a stale Hyperliquid mark blocking a configured per-transaction cap:

{
  "outcome": "rejected",
  "reasonCode": "data_unavailable",
  "humanReason": "Per-transaction cap cannot be enforced — hyperliquid mark for ETH has invalid age or exceeds the 10000ms freshness limit.",
  "triggeringPolicyField": "perTxCapUsd",
  "checks": [
    {
      "checkId": "per_tx_cap",
      "status": "failed",
      "code": "data_unavailable",
      "humanReason": "Per-transaction cap cannot be enforced — hyperliquid mark for ETH has invalid age or exceeds the 10000ms freshness limit.",
      "triggeringPolicyField": "perTxCapUsd"
    }
  ],
  "dataFreshness": {
    "overall": "cached",
    "sources": [
      {
        "source": "hyperliquid:metaAndAssetCtxs",
        "status": "cached",
        "asOf": "2026-08-20T10:00:00.000Z",
        "ageMs": 15342
      }
    ]
  }
}

Use this order to identify the dependency:

State snapshots can report stale, unavailable, never_fetched, or skipped through the affected check's humanReason. For example, portfolio_leverage or protocol_exposure can fail with data_unavailable and state that the Hyperliquid source is stale. A state source might not also appear in dataFreshness.sources[]; use the failed check and its explanation as the source diagnosis.

Do not loop on a terminal degraded verdict. Wait for the named source to recover, then submit a new verification request for the current exact action. If the action, policy, or relevant state changed, the earlier verdict cannot be reused.

Agent API-key behavior

An agent API key identifies one agent and carries service-assigned default scopes. The current issuance API accepts a name and optional expiry, not a caller-selected scope set. Confirm the returned scope metadata includes the permissions your integration requires. Use the key in the x-api-key header; never place it in a URL.

The secret is returned only when a key is issued. Later key listings expose metadata such as the key ID, name, scopes, active state, expiry, creation time, and last-used time, but not the secret. Revoking a key disables that credential without erasing the agent's existing verdict history.

Planned rotation

For planned rotation, issue the replacement before revoking the old key:

Suspected exposure

If a key may be exposed, revoke the exposed key first. Pause new submissions, remove the secret from every runtime and delivery system, issue a replacement, and redeploy it through the normal secret path. Review the agent's verdict history from the earliest suspected exposure time and investigate unfamiliar request hashes or actions. Request fresh verdicts for any in-flight action whose status or integrity is uncertain.

Incident response

Treat suspected credential exposure, persistent service failures, repeated degraded verdicts, and an unexpected verdict/action mismatch as incidents.

See the API reference for the complete verdict shape and HTTP status handling.