Error Reference

All error responses from the XOXNO Relayer WebSocket API are documented here, covering WebSocket-level control errors and transaction-level processing errors.

---

Error Response Format

Errors arrive as JSON messages with a status of "fail" (for control actions) or as entries in the failed array (for relay/broadcast actions).

Control action error (subscribe / unsubscribe)

{
  "action": "subscribe",
  "status": "fail",
  "reason": "topic limit reached"
}

Transaction action error (relay / broadcast)

{
  "action": "relay",
  "status": "failed",
  "requestId": "relay-001",
  "hashes": [],
  "failed": [
    { "index": 0, "reason": "missing relayer" }
  ]
}

---

WebSocket-Level Errors

These errors are returned in response to subscribe, unsubscribe, or other control messages.

Error Reason	Cause	Resolution
topic limit reached	The connection already has 64 active topic subscriptions	Unsubscribe from unused topics before subscribing to new ones
rate limit exceeded	More than 64 control messages were sent within a 5-second window	Implement client-side rate limiting. Batch subscriptions at connection open instead of sending individual messages in rapid succession.
invalid bech32 address in topic	The address in an address/{bech32} topic failed bech32 decode or is not a valid erd1... address	Validate addresses before subscribing
unknown topic	The topic string does not match any supported pattern	Check the supported topics list in the README
message too large	A single WebSocket frame exceeded the 4 MB limit	Split large batch payloads into smaller messages

---

Transaction Errors — Relay Action

These errors appear in failed[].reason of a relay response, each mapping to a specific validation failure in the co-signing pipeline.

Error String	Cause	Resolution
missing relayer	The transaction object does not contain a relayer field	Add the relayer field set to the shard-specific relayer address before the user signs
shard mismatch: sender_shard=X, relayer_shard=Y	The sender's shard (derived from their address) does not match the shard of the provided relayer address	Use getRelayerForSender(senderAddress) to select the correct relayer address. See the Transaction Relaying page.
unconfigured relayer	The relayer field contains an address not recognized as one of the deployed shard relayer keys	Use only the addresses listed in Transaction Relaying
signing capacity exceeded, try again later	The relayer's signing queue is full	Back off and retry. Use exponential backoff starting at 500ms.

---

Transaction Errors — Broadcast Action

These errors appear in failed[].reason of a broadcast response, returned when the network or the relayer's pre-validation rejects a transaction.

Error String	Cause	Resolution
invalid signature	The signature field does not match the canonical serialization of the transaction	Verify the signing serialization matches the MultiversX specification. Ensure all required fields are present before signing.
invalid nonce	The nonce is already consumed or too far ahead of the current account nonce	Fetch the current nonce from the API before constructing the transaction
insufficient balance	The sender account does not have enough EGLD to cover value + gasPrice * gasLimit	Check account balance before sending
invalid receiver	The receiver field is not a valid bech32 address	Validate the receiver address client-side before submitting
gas limit too low	gasLimit is below the minimum required for the transaction type	Use the gas estimation from the MultiversX SDK or increase gasLimit
invalid chain id	The chainID does not match the network (e.g., "T" submitted to mainnet)	Set chainID to "1" for mainnet

---

Subscription Response Codes

These appear in the status field of acknowledgments for subscribe and unsubscribe actions.

Status	Meaning
ok	The action succeeded
fail	The action failed. Check the reason field.

---

Handling Errors in Code

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  // Control action error
  if (msg.status === 'fail') {
    console.error(`Action "${msg.action}" failed: ${msg.reason}`);

    if (msg.reason === 'rate limit exceeded') {
      // Stop sending control messages for the remainder of the 5-second window
      scheduleRetry(5000);
    }

    if (msg.reason === 'topic limit reached') {
      // Prune stale subscriptions before adding new ones
      pruneSubscriptions();
    }

    return;
  }

  // Transaction action errors
  if ((msg.action === 'relay' || msg.action === 'broadcast') && msg.failed?.length > 0) {
    for (const failure of msg.failed) {
      console.error(`TX[${failure.index}] failed: ${failure.reason}`);

      if (failure.reason === 'signing capacity exceeded, try again later') {
        retryWithBackoff(failure.index);
      }

      if (failure.reason?.startsWith('shard mismatch')) {
        // Extract shards from error string for diagnostic logging
        console.error('Shard mismatch — check relayer address selection logic');
      }
    }
  }
};

---

Related Pages

• Transaction Relaying — Relay-specific errors and shard routing

• Transaction Broadcasting — Broadcast-specific errors

• Account Subscriptions — Subscription topic errors

• README — Connection limits and rate limit parameters