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.

Money movement (/fund, /mint, /transfer, /redeem) is asynchronous. The HTTP codes below cover what can be checked in the request (input, wallet, caps, public balances, configuration). Anything that goes wrong while the background worker executes the operation does not produce an HTTP error at all: the transaction becomes status: "FAILED" with error and errorCode set. That catalog is in Asynchronous failures below.

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, too many decimals, not a decimal string in human units, or (Aro Mail) above the per-letter cap.
`invalid_recipient`	`to` is not a valid address, or is the sending wallet itself.
`wallet_not_custodial`	Money movement (mint, transfer, redeem, letter creation) requires a custodial wallet; the given `walletId` is external (watch-only).
`insufficient_balance`	`POST /transfer` with `type: "public"`: the wallet’s public stablecoin balance is below `amount` at request time.
`insufficient_stable`	`POST /mint` in backed mode: the wallet’s public stablecoin balance is below `amount` at request time.
`faucet_cap_exceeded`	`POST /fund`: the rolling 24 h faucet cap would be exceeded (queued and pending faucet requests count).
`receipt_unavailable`	`GET /transactions/{id}/nota` for a transaction that `FAILED` before anything was submitted; `details.retryable` is `false` and no receipt will ever exist. (While still in flight the same code is returned as `409`, see below.)
`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.
`insufficient_confidential_balance`	`POST /transfer/letter`: the sending wallet’s cAROUSD balance is below `amount` at request time, or the escrow transfer clamped to zero; the Aro Mail letter is `FAILED` and nothing moved. (For private transfers and redeems the same condition surfaces asynchronously as a transaction `errorCode`, see below.)
`invalid_postal_address`	An Aro Mail recipient address fails the destination country’s rules (US: two-letter state, ZIP/ZIP+4, 64-character lines; elsewhere `region` or `postal` required; `line2 + landmark` over the limit), or Lob rejected it when mailing. The message says which.
`country_not_supported`	The Aro Mail destination country is on the deployment’s block list or not on its allow list.
`invalid_claim_code`	An Aro Mail claim code is malformed (wrong length or characters after normalisation) or its checksum does not match.
`letter_not_escrowed`	`POST /transfer/letter/{id}/mail` or `/void` on a letter that is not in an allowed state (`ESCROWED`; `MAILED` for void with acknowledgement).
`void_requires_acknowledgement`	Void of a `MAILED` letter without `acknowledgeMailed: true`.
`letter_already_mailed`	`/mail` called on a letter that is already `MAILED`.
`delivery_method_unavailable`	`deliveryMethod: "courier"`; only `standard` and `tracked` are offered.
`cannot_claim_own_letter`	The sender (same account, or a wallet at the sending address) tried to claim their own letter. Use `/void` instead.
`claim_origin_not_public`	Mailing requested, but the claim origin fixed at creation is not `https:`; paper cannot be corrected later.

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.
`unauthorized`	`POST /transfer/letter/sweep` called with a bearer token that does not match the deployment’s sweep secret. API keys and sessions are never accepted there.

402 Payment required

Code	Meaning
`postage_unavailable`	Lob could not accept the letter for mailing: provider outage, timeout, or a rejection unrelated to the address (the message carries Lob’s reason). The letter stays `ESCROWED`; retry `/mail` or print it yourself.

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. Also appears as a transaction `errorCode` when the account is deactivated after a money-movement request was queued but before the worker executed it.
`recipient_blocked`	Reserved: an Aro Mail recipient was blocked by a screening provider. The MVP applies only the country allow/block lists, which surface as `400 country_not_supported`.

404 Not found

Code	Meaning
`not_found`	Resource doesn’t exist within your account; foreign IDs read as 404 by design. Also returned by `POST /fund` on production, where the faucet does not exist (sandbox-only feature), and by `POST /transfer/letter/sweep` when the deployment has no sweep secret configured.
`letter_not_found`	No Aro Mail letter with this id in your account, or no letter matches the claim code (the preview and claim endpoints never say which).

409 Conflict

Code	Meaning
`wallet_exists`	The address is already registered to a wallet.
`passkey_exists`	This authenticator credential is already registered.
`receipt_unavailable`	`GET /transactions/{id}/nota` while the transaction is still `QUEUED` (no hash yet). `details` carries the current `status` and `retryable: true`; retry once the worker has submitted it.
`already_claimed`	Another principal or wallet already won the claim on this letter (`CLAIMING` or `CLAIMED`). The same claimant calling again gets the existing claim back instead.
`letter_not_claimable`	Claim on a letter that is `DRAFT`, `VOIDED` or `FAILED`, including a mailed letter the sender voided with `acknowledgeMailed: true`.
`letter_not_printable`	PDF requested for a `DRAFT` or `FAILED` letter; the value is not escrowed yet (or never was).
`sweep_in_progress`	A sweep is already running in this process; let it finish.

410 Gone

Code	Meaning
`letter_expired`	Claim attempted after the letter’s `expiresAt`. The sender is refunded automatically.

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.
`letter_velocity_limit`	Too many Aro Mail letters in flight (`DRAFT`, `ESCROWED`, `MAILED`, `CLAIMING`) for this sender or for the destination country, or the creation transaction hit a serialization conflict; retry after a moment or once letters settle.

500 Internal error

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

502 Upstream failure

Two kinds of endpoint can return 502: read endpoints that talk to the confidential-rail relayer inline, and the two Aro Mail calls that broadcast a transaction inline (POST /transfer/letter and POST /transfer/letter/claim). The queued money-movement endpoints (/fund, /mint, /transfer, /redeem) never do: on-chain and relayer problems during execution become status: "FAILED" on the transaction (see the next section), and transient ones are retried by the worker without surfacing.

Code	Meaning
`fhe_init_failed`	The confidential-rail relayer could not be initialized. Transient; retry with backoff. (`GET /balances` degrades to encrypted-only instead of failing.)
`fhe_decryption_failed`	A confidential balance could not be decrypted through the relayer. Transient; retry with backoff.
`transfer_failed`	`POST /transfer/letter`: the escrow transfer reverted on-chain; the letter is `FAILED` and nothing left the wallet. (For `POST /transfer` the same code is an asynchronous `errorCode`, see below.)
`claim_failed`	The Aro Mail release transfer reverted on-chain. The letter returns to `ESCROWED`/`MAILED` and can be claimed again.
`escrow_unsettled`	`POST /transfer/letter` broadcast the escrow transfer (its hash is in `message` and on the `LETTER_ESCROW` transaction row) but could not finish the bookkeeping. Value has very likely left your wallet: the letter stays `DRAFT` with `error` set and is finished by reconciliation on its next read (`GET /transfer/letter` or `GET /transfer/letter/{id}`) or by the sweep. Do not create the letter again; find it in your letter list and poll it.
`claim_unsettled`	`POST /transfer/letter/claim` broadcast the release transfer but could not finish the bookkeeping. The letter stays `CLAIMING` for you and reconciliation completes it to `CLAIMED`; repeating the same claim call from the same account is idempotent and returns the in-progress claim. Do not treat it as a revert.

For escrow_unsettled and claim_unsettled, error.details carries { letterId, txHash } so a client can follow the letter with GET /transfer/letter/{id} instead of creating or claiming it again. Both mean the transaction was broadcast; only the bookkeeping is pending and reconciliation finishes it.

For the Aro Mail *_failed codes the call also records a LETTER_* transaction row with status: "FAILED" and the revert context in error; check GET /transactions for the audit trail. The *_unsettled codes are different: the transaction was broadcast, so its row stays PENDING with a txHash until reconciliation verifies the receipt. 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. On money-movement endpoints these are checked before anything is queued, so a 503 means no transaction row was created.

Code	Meaning
`rail_rpc_chain_mismatch`	The platform’s RPC endpoint serves a different chain than the deployment targets. Platform-side misconfiguration; report it.
`stable_misconfigured`	The platform’s configured stablecoin is not a contract on the active chain. Platform-side misconfiguration; report it.
`wallet_key_unreadable`	`POST /wallets/{id}/export`: the platform could not decrypt the custodial wallet key (master-key mismatch). Platform-side; report it. For money movement the same condition surfaces asynchronously as a transaction `errorCode`.
`fhe_unsupported_chain`	The deployment targets a chain without a Zama Protocol deployment; confidential operations are unavailable there.
`fhe_credentials_missing`	The Mainnet deployment has no FHE relayer credentials configured yet; confidential operations are disabled until the platform sets them.
`mail_provider_not_configured`	Aro Mail mailing is unavailable: the print provider key is missing or rejected, or the operator’s return address is incomplete. Platform-side; `GET /transfer/letter/rules` reports `mailing.available`. Printing the PDF yourself still works.
`public_url_not_configured`	`AROPAY_PUBLIC_URL` is unset on a production deployment, so no claim URL can be fixed for the letter. Platform-side.
`escrow_vault_underfunded`	The operator’s cAROUSD balance is below the payout (or the payout clamped to zero), so the release or refund was not made. The letter stays claimable; the platform must top the vault up.

Asynchronous failures (`transaction.errorCode`)

Money-movement requests return 201 with a QUEUED transaction; a background worker then executes it. When execution cannot proceed, the worker marks the transaction FAILED and sets two fields:

{
  "id": "cktxn0002…",
  "type": "MINT",
  "status": "FAILED",
  "txHash": null,
  "error": "Mint reverted on-chain. The sandbox operator may be missing ROLE_MINTER.",
  "errorCode": "mint_failed"
}

error is human-readable and may be reworded; errorCode is the stable key. Both are null on every non-FAILED transaction.

FAILED always means nothing moved on-chain for that row. A transaction is failed only when a pre-flight check rejected it before anything was broadcast, or when the on-chain call reverted (a revert moves no funds). A broadcast transaction whose outcome is still unknown stays PENDING (or SETTLING for a redeem payout) and keeps being tracked; it is never failed underneath you.

`errorCode`	Types	Meaning
`insufficient_stable`	`MINT` (backed)	The wallet’s public stablecoin balance is below `amount` when the worker runs (a competing debit landed after the request-time check).
`insufficient_balance`	`TRANSFER`	The wallet’s public stablecoin balance is below `amount` when the worker runs.
`insufficient_confidential_balance`	`PRIVATE_TRANSFER`, `REDEEM`	The decrypted cAROUSD balance, minus other queued/pending debits from the same wallet, cannot cover `amount`. The worker re-checks for a few minutes before failing, so a just-confirmed mint is picked up.
`faucet_cap_exceeded`	`FUND`	The rolling 24 h cap was exceeded when re-checked at execution time.
`account_disabled`	all	The account was deactivated between the request and execution.
`wallet_unavailable`	all	The wallet was deleted, is not custodial, or has no signing material by the time the worker picked the job up.
`wallet_key_unreadable`	all	The custodial key could not be decrypted (platform master-key mismatch). Platform-side; report it.
`invalid_amount`	all	The stored amount could not be converted for the token (e.g. exceeds the on-chain uint64 range).
`faucet_failed`	`FUND`	The operator’s gas top-up or stablecoin transfer reverted (usually operator liquidity). Platform-side.
`mint_failed`	`MINT`	The mint (or its `approve` step) reverted: missing `ROLE_MINTER` in float mode; allow-listing or deposit issues in backed mode. Platform-side.
`transfer_failed`	`TRANSFER`, `PRIVATE_TRANSFER`	The transfer reverted on-chain.
`redeem_failed`	`REDEEM`	The burn/request leg (or its `setOperator` step) reverted on-chain.
`transaction_dropped`	any (legacy rows)	A transaction submitted by the previous, synchronous implementation was dropped from the network before being mined and cannot be re-broadcast. Not produced for transactions created after the worker rollout, which are re-broadcast automatically.
`job_exhausted`	all	The worker gave up after repeated transient errors (RPC or relayer outages) without ever broadcasting. `error` carries the last cause; safe to resubmit.

Codes that no longer exist: approval_timeout, operator_approval_timeout, redeem_settlement_pending, and redeem_settlement_failed. A redeem payout that cannot be sent yet keeps the row in SETTLING and is retried.

Symptom-level fixes for each code live in Troubleshooting.

Using the API

Auth

Profile & security

API keys

Wallets

Balances

Money movement

Aro Mail

Transactions

Sandbox

400 Bad request

401 Unauthenticated

402 Payment required

403 Forbidden

404 Not found

409 Conflict

410 Gone

415 Unsupported media type

429 Too many requests

500 Internal error

502 Upstream failure

503 Configuration

Asynchronous failures (`transaction.errorCode`)

​400 Bad request

​401 Unauthenticated

​402 Payment required

​403 Forbidden

​404 Not found

​409 Conflict

​410 Gone

​415 Unsupported media type

​429 Too many requests

​500 Internal error

​502 Upstream failure

​503 Configuration

​Asynchronous failures (transaction.errorCode)

400 Bad request

401 Unauthenticated

402 Payment required

403 Forbidden

404 Not found

409 Conflict

410 Gone

415 Unsupported media type

429 Too many requests

500 Internal error

502 Upstream failure

503 Configuration

Asynchronous failures (`transaction.errorCode`)