Errors

The error envelope and the complete catalog of error codes, grouped by HTTP status.

Failures always use the shared envelope: HTTP status gives you the class, error.code the specific condition, error.message a human-readable explanation, and error.details structured context where it exists:

{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": [
      { "path": "amount", "message": "Required" }
    ]
  }
}

Match on error.code, not message; messages are for humans and may be reworded. The two flat Sandbox probes are the only endpoints that don’t use this envelope.

400 Bad request

Code	Meaning
invalid_json	Body is not parseable JSON.
validation_error	Schema violation; details lists { path, message } per offending field.
invalid_request	The request is structurally valid but not usable in this state.
invalid_amount	Amount missing, non-positive, or not a decimal string in human units.
invalid_recipient	to is not a valid address.
invalid_nota	The supplied .nota payload is not a valid resource of the expected kind.
weak_password	New password fails policy (≥10 chars, upper + lower + digit).
totp_already_enabled	TOTP setup called while 2FA is already on.
totp_not_configured	Enable/disable called with no pending or active TOTP enrollment.
invalid_totp_code	The 6-digit code is wrong or reused (also appears as 401 during login).
invalid_challenge	WebAuthn challenge missing, malformed, or already used.
challenge_expired	WebAuthn challenge outlived its validity window.
passkey_verification_failed	WebAuthn attestation could not be verified (during registration; 401 during login).
invalid_host	WebAuthn origin/host mismatch.
wallet_limit_reached	Account already has 10 wallets.
key_limit_reached	Account already has 10 active API keys.

401 Unauthenticated

Code	Meaning
unauthenticated	No credential presented.
invalid_api_key	Bearer token unknown, revoked, expired, or malformed.
session_expired	Session cookie no longer valid (TTL or token-version bump).
invalid_credentials	Wrong email/password (also returned while locked out; deliberately indistinguishable).
invalid_totp_code	Wrong/expired code or pending token during two-step login.
unknown_passkey	Assertion from an authenticator not registered to any account.
passkey_verification_failed	WebAuthn assertion failed verification at login.

403 Forbidden

Code	Meaning
session_required	Endpoint is session-only and was called with an API key.
account_disabled	The account has been deactivated by an admin.

404 Not found

Code	Meaning
not_found	Resource doesn’t exist within your account; foreign IDs read as 404 by design.

409 Conflict

Code	Meaning
wallet_exists	The address is already registered in the sandbox.
passkey_exists	This authenticator credential is already registered.

415 Unsupported media type

Code	Meaning
unsupported_media_type	Write request without Content-Type: application/json.

429 Too many requests

Code	Meaning
rate_limited	A rate limit was exceeded. Back off with jitter.

500 Internal error

Code	Meaning
internal_error	Unexpected failure. Nothing about your request caused it; safe to retry with backoff.

502 Upstream / on-chain failure

Code	Meaning
faucet_failed	Operator couldn’t fund the wallet (usually operator liquidity/gas).
mint_failed	Mint reverted on-chain (missing ROLE_MINTER in float mode; allow-listing or deposit issues in backed mode).
transfer_failed	Transfer reverted on-chain.
redeem_failed	Redeem burn/request leg reverted.
redeem_settlement_failed	Redeem payout leg failed (operator liquidity/gas).

For 502s, the money-movement call also records a transaction row with status: "FAILED" and the revert context in error; check GET /transactions for the audit trail. Symptom-level fixes live in Troubleshooting.

503 Configuration

A 503 naming an environment variable means the deployment is missing required configuration. Platform-side; report the message text to your admin.