> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aropay.aro.media/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Symptom-to-cause table for the errors you're most likely to hit, and what to do about each.

Start with the [error envelope](/api-reference/errors); `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](/security/authentication#session-only-endpoints) 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](/security/rate-limits). 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](/guides/fund-a-wallet) 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's `error.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.