Error codes
The stable, machine-readable error codes PolicyVault's API and clients use — passed back verbatim, never remapped.
Every PolicyVault API error carries a stable code, an HTTP status, and a human-readable message. Clients (the JavaScript SDK, the Python client) surface this envelope verbatim — never remapped, upgraded, or silently reinterpreted. This page lists the codes visible in PolicyVault's public source; it is not necessarily exhaustive of every route-specific extra field.
Request / input validation (4xx)
| Code | Status | Meaning |
|---|---|---|
BAD_ACTION | 400 | The requested action is not recognized for this route/version. |
BAD_ADDRESS | 400 | An address failed to parse or resolve. See KasWare signing problems if this happens during wallet connection. |
BAD_APPROVER | 400 | An approver reference is invalid. |
BAD_CURSOR | 400 | A pagination cursor is malformed. |
BAD_FORMAT | 400 | A field's format does not match what is required. |
BAD_SIGNATURE | 400 | A supplied signature failed shape validation. |
BAD_SIGNER | 400 | The signer identity supplied is invalid for this operation. |
BAD_VAULT_ID | 400 | The vault id is malformed. |
COMPRESSED_OWNER_PUBKEY | 422 | An owner public key was supplied in compressed form where the normalized x-only form is required; this is a diagnostic refusal, not an automatic normalization. |
UNKNOWN_FIELD | 422 | The request body carries a field outside the permitted, closed set for this route — refused so a hidden field can never produce a hidden effect. |
UNKNOWN_DEV_ACCOUNT | 400 | Reference to a test-only dev account that does not exist (non-production only). |
UNSUPPORTED_VERSION | 422 | A covenant, schema, or protocol version is not recognized. Fails closed — never routed to a default. |
SCHEMA_VERSION_UNSUPPORTED | 422 | The request body's declared schema version does not match what the server speaks. |
ADDRESS_WRONG_NETWORK / DONATION_WRONG_NETWORK | — | An address is valid in form but for the wrong Kaspa network family. |
Funds / policy refusals (4xx)
| Code | Status | Meaning |
|---|---|---|
INSUFFICIENT_FUNDS | 422 | The vault does not have sufficient balance for the requested operation. |
BAD_DEPOSIT | 422 | A deposit/top-up amount or structure is invalid. |
INTENT_VERIFICATION_FAILED | 422 | The independently derived intent manifest did not match what was requested — see Local intent verification. |
RISK_REVIEW_REQUIRED | — | The restrictive-only risk pipeline is holding this request for review before it can proceed; see Reference → Terminology for the risk-pipeline model. |
Authorization / access (401/403/404)
| Code | Status | Meaning |
|---|---|---|
SESSION_INVALID | 401 | The hosted wallet session is missing or invalid. |
MACHINE_TOKEN_INVALID | 401 | A machine credential failed authentication. |
SCOPE_FORBIDDEN | 403 | The authenticated machine identity does not hold a scope this route requires. See Machine identities and capabilities. |
MACHINE_IDENTITY_ROUTE_FORBIDDEN | 403 | Identity-management routes are refused for any machine credential, regardless of scope — a structural, wallet-session-only exclusion. |
LEGACY_CREATE_DISABLED | 403 | An older creation path is disabled on this deployment. |
REQUEST_FORBIDDEN | 403 | The caller is not authorized to act on this specific request. |
ORIGIN_REQUIRED | 403 | A cookie-authenticated mutation was attempted without a valid Origin — the CSRF/origin gate; does not apply to bearer-token programmatic callers. |
AUTH_DISABLED | 404 | Hosted authentication is not enabled on this deployment (self-hosted mode). |
DEV_SIGNER_DISABLED | 404 | The test-only dev signer is not enabled on this deployment (never enabled in production). |
NOT_FOUND | 404 | Generic not-found. |
VAULT_NOT_FOUND / REQUEST_NOT_FOUND / MANIFEST_NOT_FOUND / GOVERNANCE_PROPOSAL_UNKNOWN / RISK_EVALUATION_NOT_FOUND / ASSIGNMENT_NOT_FOUND | 404 | The referenced object does not exist — or does exist but belongs to a different tenant, in which case it is deliberately reported identically to "does not exist" (see Tenant isolation). |
Idempotency and concurrency (409)
| Code | Status | Meaning |
|---|---|---|
IDEMPOTENCY_KEY_CONFLICT | 409 | The same idempotency key was reused with a different request body — refused rather than reinterpreted. |
IDEMPOTENCY_IN_PROGRESS | 409 | A genuinely concurrent duplicate call with the same key is already executing. |
VERSION_CONFLICT | 409 | An optimistic-concurrency expectedVersion did not match — a competing write happened first; retry against the current version rather than silently overwriting it. |
ORG_NOT_EMPTY | 409 | An organization deletion/operation was refused because it still has dependent records. |
Server-side integrity (422/5xx)
| Code | Status | Meaning |
|---|---|---|
RECONCILE_FAILED | 422 | Chain reconciliation could not resolve a held claim's outcome from available evidence. |
TXID_MISMATCH | — | A signed transaction's actual id did not match the frozen id it was expected to have — refused before submission. |
EVENT_TYPE_UNKNOWN | 422 | An event/webhook type is not recognized. |
DEV_SIGN_FAILED | 422 | The test-only dev signer failed (non-production only). |
CORRUPT_METADATA | — | Application metadata (for example, an organization record) failed to parse; the affected object degrades to an unassigned/unlabeled presentation rather than hiding funds or crashing. |
METHOD_NOT_ALLOWED | 405 | The HTTP method is not valid for this route. |
Client-side wallet/signer errors (not HTTP codes)
These are normalized by the wallet-adapter layer, not returned by the API — see What wallets and signers do:
WALLET_NOT_FOUND, WALLET_DISCONNECTED, USER_REJECTED, WRONG_NETWORK, ACCOUNT_CHANGED, SIGNING_UNSUPPORTED, INVALID_SIGNATURE_RESPONSE, INVALID_PUBLIC_KEY, PROVIDER_ERROR.
See also: REST API, Troubleshoot a pending request.