> ## 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.

# 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:

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

<Note>
  Match on `error.code`, not `message`; messages are for humans and may be
  reworded. The two flat [Sandbox](/api-reference/introduction#sandbox-endpoints)
  probes are the only endpoints that don't use this envelope.
</Note>

## 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](/security/authentication#session-only-endpoints) 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](/security/rate-limits) 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).                                                            |

<Tip>
  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](/support/troubleshooting).
</Tip>

## 503 Configuration

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