Error Reference

The mandate token could not be decoded — truncated, corrupted, or not a mandate token at all.

Recover: Check you are passing the token string exactly as returned by issue*Mandate. Do not re-encode or trim it.

The mandate's expiry timestamp has passed. Mandates are short-lived by design (default: minutes).

Recover: Issue a fresh mandate. Do not extend TTLs as a workaround — short expiry is the security model.

The mandate was issued to a different DID than the one presenting it.

Recover: Verify you are passing the correct expectedGrantee. A mandate is bound to exactly one grantee DID.

The grantor rotated their keypair after signing this mandate — the old key is revoked.

Recover: Request a new mandate signed with the grantor's current key. Fetch the latest key from the registry.

The spending mandate failed verification before the spend was attempted.

Recover: See mandate verification errors above — the .message contains the underlying reason.

The attempted charge exceeds the mandate's spendLimitUsd. Enforced cryptographically — cannot be bypassed.

Recover: Request a mandate with a higher limit from the human issuer, or reduce the transaction amount.

The task mandate failed verification.

Recover: See mandate verification errors — the .message contains the underlying reason.

The capability being invoked is not in the mandate's allowed list (or is explicitly blocked).

Recover: Check mandate.constraints.allowed / blocked. Request a mandate covering this capability.

The mandate has reversibleOnly: true and this capability has irreversible side effects.

Recover: Either use a reversible alternative, or ask the issuer for a mandate without reversibleOnly.

This capability is listed in humanGates — execution pauses until the human approves.

Recover: Not an error to retry. Surface the approval_required event to the user and resume via POST /v1/resume after approval.

The per-capability invocation budget (actionLimits) is spent.

Recover: The task is over-budget by design. Complete with what you have, or request a mandate with higher limits.

LLM token or web-request budget (computeLimit) is exhausted.

Recover: Same as ACTION_LIMIT_EXCEEDED — budgets are hard stops, not suggestions.

The task attempted to access a data scope not granted by the mandate.

Recover: Check mandate.constraints.dataAccess. Request broader scope from the issuer if genuinely needed.

The mandate requires execution inside a sandbox and the runtime is not sandboxed.

Recover: Run the task in a sandboxed executor, or request a mandate without the sandbox requirement.

Request body is not valid JSON.

Recover: Check Content-Type: application/json and body encoding.

DID missing or does not match did:aroha:<name> format.

Recover: DIDs must match /^did:aroha:[a-z0-9][a-z0-9:._-]+$/i.

publicKeyB64 is not a base64-encoded 32-byte raw Ed25519 public key.

Recover: Export the raw (not PEM/PKCS8) public key and base64-encode it.

Agent key challenge failed — expired, tampered, or issued for a different DID/key.

Recover: Request a fresh challenge (they expire after 5 minutes) and retry within the window.

Ed25519 signature over the challenge string does not verify.

Recover: Sign the exact challenge string (UTF-8 bytes) with the private key matching publicKeyB64.

Too many requests from this IP.

Recover: Honor retryAfterSeconds in the response body before retrying.

Registration requires did, manifestCID, and publicKeyB64.

Recover: Pin your manifest to IPFS first, then register with all three fields.

The Bearer key is unknown, revoked, or malformed.

Recover: Create a key via /keys (signed in) or the agent-request flow, and send it as Authorization: Bearer <key>.

Another record owns this DID.

Recover: DIDs are globally unique. Choose a different DID, or update your existing record with your owner key.