Mera
ExecutionInstant confidential swapsClear from encrypted balances in one 150ms slot.Hidden-size limit ordersLock encrypted size in a private escrow PDA.Sealed RFQ block tradesRequest signed quotes without leaking size.
Vault & AuditShielded vault & keysDeposit SOL, SPL, or Token-2022 into a Ring.Viewing key verifierDecrypt and prove a single settled fill.
Docs/Protocol & Reference
4 min read

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

CodeHTTPMeaning and recovery
INSUFFICIENT_SHIELDED_BALANCE400No 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_TVK400TVK is missing the mera_tvk_v1_ prefix, malformed base64/JSON, or its recomputed SHA-256 settlement commitment hash does not match commitmentHash.
PAIR_NOT_SUPPORTED400Requested pairId is not registered. Query GET /v1/pairs for valid IDs.
RING_ACCESS_DENIED403Wallet is not allowlisted on this Custom Ring. Ask the Ring authority to allowlist the wallet via set_ring_member.
RING_FROZEN403Either the Ring itself (RingConfig.frozen) or the wallet's RingMember record is frozen.
QUOTE_EXPIRED409The swap quote (25s TTL) or RFQ quote (ttlSeconds) expired or was already consumed. Request a fresh quote.
ORDER_NOT_OPEN409The target PrivateEscrowOrder is already filled, cancelled, or expired.

Base API error codes

CodeHTTPMeaning and recovery
VALIDATION_ERROR400Request body or query failed zod schema validation. Inspect error.fieldErrors for per-field details.
UNAUTHORIZED401Missing/expired SIWS session token, reused nonce, or caller is not the Ring authority.
ORIGIN_NOT_ALLOWED403Request Origin header is not permitted by CORS policy.
NOT_FOUND404Referenced Ring, quote, order, RFQ request, or transaction build ID does not exist.
PROGRAM_UNAVAILABLE409On-chain mera_core program is not yet initialized on the target cluster.
CONFIGURATION_REQUIRED409Required server configuration (such as a maker co-signer) is not enabled.
IDEMPOTENCY_CONFLICT409Duplicate request with conflicting parameters for the same idempotency key.
TRANSACTION_EXPIRED409Transaction blockhash passed lastValidBlockHeight before confirmation. Rebuild and re-sign.
PAYLOAD_TOO_LARGE413Request payload exceeds server body size limit.
UNSUPPORTED_MEDIA_TYPE415Request Content-Type must be application/json.
SIMULATION_FAILED422Pre-flight transaction simulation failed. Check error.programError.
CHAIN_REFUSED422Solana validator rejected the submitted transaction. Check error.programError and error.message.
RATE_LIMITED429Client exceeded the /v1/* rate limit. Wait error.retryAfterSeconds before retrying.
INTERNAL_ERROR500Unexpected server error. Retry with backoff if retryable is true.
UPSTREAM_UNAVAILABLE502RPC 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):

NumberNameMessageRaised when
6000InvalidFeeBpsProtocol fee bps exceeds maximum allowed (500 bps)init_protocol or update_protocol_fee receives fee_bps > 500.
6001ProtocolPausedMera protocol is currently pausedcreate_ring, deposit_shielded, place_hidden_order, fill_hidden_order, settle_confidential_swap, or settle_sealed_rfq is called while ProtocolConfig.paused == true.
6002InvalidRingNameInvalid ring name lengthcreate_ring receives a name shorter than 2 or longer than 48 bytes.
6003InvalidRingModeInvalid ring modecreate_ring receives mode > 1.
6004RingFrozenRing is currently frozenDeposit, withdraw, order placement, or settlement targets a Ring with RingConfig.frozen == true.
6005ZeroAmountAmount must be greater than zeroDeposit, withdraw, order amount, limit price, or settlement amount is 0.
6006NoteAlreadySpentCommitment note has already been spentAn input CommitmentNote already has spent == true.
6007InsufficientShieldedBalanceInsufficient shielded commitment balanceInput CommitmentNote.amount is less than the requested withdrawal, escrow, or trade amount.
6008UnauthorizedUnauthorized signer for this actionSigner does not match ProtocolConfig.admin, RingConfig.authority, CommitmentNote.owner, or PrivateEscrowOrder.maker (before expiry_slot).
6009InvalidOrderSideInvalid order sideplace_hidden_order receives side > 1.
6010OrderNotOpenPrivate escrow order is not opencancel_hidden_order or fill_hidden_order targets an escrow with status != 0.
6011OrderExpiredPrivate escrow order has expiredplace_hidden_order receives expiry_slot <= clock.slot, or fill_hidden_order runs at clock.slot >= expiry_slot.
6012InvalidAccountInvalid account passed to instructionA passed note, vault, escrow, or fee token account does not match the expected Ring or mint.
6013InvalidFeeRecipientFee recipient token account does not match protocol fee recipientfee_recipient_token_account.owner != protocol_config.fee_recipient.
6014MathOverflowArithmetic overflowA checked u64 or u128 addition, subtraction, or multiplication overflowed.