Errors

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.

Using the API

Auth

Profile & security

API keys

Wallets

Balances

Money movement

Transactions

Sandbox

400 Bad request

401 Unauthenticated

403 Forbidden

404 Not found

409 Conflict

415 Unsupported media type

429 Too many requests

500 Internal error

502 Upstream / on-chain failure

503 Configuration

​400 Bad request

​401 Unauthenticated

​403 Forbidden

​404 Not found

​409 Conflict

​415 Unsupported media type

​429 Too many requests

​500 Internal error

​502 Upstream / on-chain failure

​503 Configuration

400 Bad request

401 Unauthenticated

403 Forbidden

404 Not found

409 Conflict

415 Unsupported media type

429 Too many requests

500 Internal error

502 Upstream / on-chain failure

503 Configuration