error.code is the
machine-readable key to everything below.
Auth & access
| Symptom | Likely cause / fix |
|---|---|
401 invalid_api_key | Key revoked, expired, or mistyped. Check GET /keys from the dashboard; create a fresh key if needed. |
401 unauthenticated | No credential at all: missing Authorization header and no session cookie. |
401 session_expired | The 24 h session TTL passed, or a password change invalidated it. Sign in again. |
403 session_required | You called a session-only endpoint with an API key. Do it from the dashboard or a cookie-authenticated call. |
403 account_disabled | The account was deactivated by an admin. Contact your Aro Media admin. |
401 invalid_credentials on every login | Wrong email/password, or the account is locked after 5 failures (wait 15 min). The response deliberately doesn’t distinguish. |
429 rate_limited | You exceeded a rate limit. Back off with jitter. |
Requests
| Symptom | Likely cause / fix |
|---|---|
415 unsupported_media_type | Write request without Content-Type: application/json. |
400 invalid_json | Body isn’t parseable JSON. |
400 validation_error | Schema violation; error.details lists { path, message } per field. |
400 invalid_amount | Amount must be a positive decimal string in human units ("25.50"). |
404 not_found | The ID doesn’t exist in your account; cross-account IDs read as 404 by design. |
Money movement
| Symptom | Likely cause / fix |
|---|---|
502 faucet_failed | The platform operator wallet is out of stablecoin or ETH. Platform-side; report it. |
Faucet 400 about the cap | Rolling 24 h faucet cap reached. Wait for older requests to age out. |
502 mint_failed mentioning ROLE_MINTER | Float-mode deployment where the operator lacks the minter role. Platform-side. |
502 mint_failed mentioning allow-listing | Backed-mode deployment where the stablecoin isn’t allow-listed on the commitment. Platform-side. |
Mint 400 about balance (backed mode) | Your custodial wallet doesn’t hold enough public stablecoin; fund it first. |
Transfer/redeem 400 about wallet type | Spending requires a custodial wallet; external wallets are watch-only. |
502 transfer_failed / redeem_failed | The on-chain call reverted; the transaction row’s error field has specifics. Often gas or balance on the relevant rail. |
Redeem stuck in SETTLING | Settlement advances on read; keep polling GET /transactions/{id}. In backed mode the public decryption may not be published yet; if it persists for a long time, the operator may be out of ETH (platform-side). |
Transaction stays PENDING | Keep polling; reads trigger reconciliation. Sepolia can be slow; the row will eventually confirm or fail. |
Confidential operations
| Symptom | Likely cause / fix |
|---|---|
| First mint/balance read after a deploy is very slow | FHE keys are fetched on first use per process. Subsequent calls are faster; don’t tune timeouts to the first call. |
External wallet shows confidential.amount: null | Expected: the sandbox can’t decrypt balances it doesn’t hold keys for. encrypted: true confirms it. |
503 naming a configuration variable | The deployment is missing a required environment setting. Platform-side; report the message text. |
Receipts & files
| Symptom | Likely cause / fix |
|---|---|
400 from GET /transactions/{id}/nota | The transaction hasn’t reached the chain yet (or failed before submission). Retry after it confirms. |
400 invalid_nota registering a wallet | The file isn’t a valid Notareum address card; re-export it from the source wallet. |
Still stuck?
Grab the failing request’serror.code and error.message, the transaction
ID if there is one, and a timestamp, then contact your Aro Media admin.
Admins can reset passwords, clear 2FA, re-activate accounts, and check
operator health.