Error Codes
Complete catalog of Mera API error codes, ErrorStage values, and on-chain mera_core Anchor error codes (6000-6014).
Every failed HTTP response from Mera's API returns one structured JSON error envelope defined in @mera/contract:
json
{
"error": {
"code": "QUOTE_EXPIRED",
"message": "Swap quote has expired.",
"retryable": false,
"stage": "validation",
"requestId": "req_01j..."
}
}Error stages (`ErrorStage`)
Every error includes a stage field naming the exact step that failed:
validation, auth, read, upload, build, wallet, co_sign, simulation, send, confirmation.
When an on-chain program rejects a transaction, error.programError includes { programId, name, number } so custom codes (6000+) are attributed to the exact Solana program that raised them.
Mera-specific API error codes
| Code | HTTP | Meaning and recovery |
|---|---|---|
INSUFFICIENT_SHIELDED_BALANCE | 400 | No single unspent CommitmentNote in the Ring covers the requested withdrawal, swap, hidden order, or RFQ size. Shield additional funds or choose a smaller amount. |
INVALID_TVK | 400 | TVK is missing the mera_tvk_v1_ prefix, malformed base64/JSON, or its recomputed SHA-256 settlement commitment hash does not match commitmentHash. |
PAIR_NOT_SUPPORTED | 400 | Requested pairId is not registered. Query GET /v1/pairs for valid IDs. |
RING_ACCESS_DENIED | 403 | Wallet is not allowlisted on this Custom Ring. Ask the Ring authority to allowlist the wallet via set_ring_member. |
RING_FROZEN | 403 | Either the Ring itself (RingConfig.frozen) or the wallet's RingMember record is frozen. |
QUOTE_EXPIRED | 409 | The swap quote (25s TTL) or RFQ quote (ttlSeconds) expired or was already consumed. Request a fresh quote. |
ORDER_NOT_OPEN | 409 | The target PrivateEscrowOrder is already filled, cancelled, or expired. |
Base API error codes
| Code | HTTP | Meaning and recovery |
|---|---|---|
VALIDATION_ERROR | 400 | Request body or query failed zod schema validation. Inspect error.fieldErrors for per-field details. |
UNAUTHORIZED | 401 | Missing/expired SIWS session token, reused nonce, or caller is not the Ring authority. |
ORIGIN_NOT_ALLOWED | 403 | Request Origin header is not permitted by CORS policy. |
NOT_FOUND | 404 | Referenced Ring, quote, order, RFQ request, or transaction build ID does not exist. |
PROGRAM_UNAVAILABLE | 409 | On-chain mera_core program is not yet initialized on the target cluster. |
CONFIGURATION_REQUIRED | 409 | Required server configuration (such as a maker co-signer) is not enabled. |
IDEMPOTENCY_CONFLICT | 409 | Duplicate request with conflicting parameters for the same idempotency key. |
TRANSACTION_EXPIRED | 409 | Transaction blockhash passed lastValidBlockHeight before confirmation. Rebuild and re-sign. |
PAYLOAD_TOO_LARGE | 413 | Request payload exceeds server body size limit. |
UNSUPPORTED_MEDIA_TYPE | 415 | Request Content-Type must be application/json. |
SIMULATION_FAILED | 422 | Pre-flight transaction simulation failed. Check error.programError. |
CHAIN_REFUSED | 422 | Solana validator rejected the submitted transaction. Check error.programError and error.message. |
RATE_LIMITED | 429 | Client exceeded the /v1/* rate limit. Wait error.retryAfterSeconds before retrying. |
INTERNAL_ERROR | 500 | Unexpected server error. Retry with backoff if retryable is true. |
UPSTREAM_UNAVAILABLE | 502 | RPC node unreachable or maker shielded output inventory is temporarily replenishing. Retry shortly. |
On-chain `mera_core` errors
Anchor assigns custom error numbers sequentially starting at 6000 in MeraError (backend/program/programs/mera_core/src/lib.rs):
| Number | Name | Message | Raised when |
|---|---|---|---|
6000 | InvalidFeeBps | Protocol fee bps exceeds maximum allowed (500 bps) | init_protocol or update_protocol_fee receives fee_bps > 500. |
6001 | ProtocolPaused | Mera protocol is currently paused | create_ring, deposit_shielded, place_hidden_order, fill_hidden_order, settle_confidential_swap, or settle_sealed_rfq is called while ProtocolConfig.paused == true. |
6002 | InvalidRingName | Invalid ring name length | create_ring receives a name shorter than 2 or longer than 48 bytes. |
6003 | InvalidRingMode | Invalid ring mode | create_ring receives mode > 1. |
6004 | RingFrozen | Ring is currently frozen | Deposit, withdraw, order placement, or settlement targets a Ring with RingConfig.frozen == true. |
6005 | ZeroAmount | Amount must be greater than zero | Deposit, withdraw, order amount, limit price, or settlement amount is 0. |
6006 | NoteAlreadySpent | Commitment note has already been spent | An input CommitmentNote already has spent == true. |
6007 | InsufficientShieldedBalance | Insufficient shielded commitment balance | Input CommitmentNote.amount is less than the requested withdrawal, escrow, or trade amount. |
6008 | Unauthorized | Unauthorized signer for this action | Signer does not match ProtocolConfig.admin, RingConfig.authority, CommitmentNote.owner, or PrivateEscrowOrder.maker (before expiry_slot). |
6009 | InvalidOrderSide | Invalid order side | place_hidden_order receives side > 1. |
6010 | OrderNotOpen | Private escrow order is not open | cancel_hidden_order or fill_hidden_order targets an escrow with status != 0. |
6011 | OrderExpired | Private escrow order has expired | place_hidden_order receives expiry_slot <= clock.slot, or fill_hidden_order runs at clock.slot >= expiry_slot. |
6012 | InvalidAccount | Invalid account passed to instruction | A passed note, vault, escrow, or fee token account does not match the expected Ring or mint. |
6013 | InvalidFeeRecipient | Fee recipient token account does not match protocol fee recipient | fee_recipient_token_account.owner != protocol_config.fee_recipient. |
6014 | MathOverflow | Arithmetic overflow | A checked u64 or u128 addition, subtraction, or multiplication overflowed. |