# 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) ```json { "action": "subscribe", "status": "fail", "reason": "topic limit reached" } ``` ### Transaction action error (relay / broadcast) ```json { "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](/developers/relayer-api.md) | | `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](/developers/relayer-api/transaction-relaying.md) 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](/developers/relayer-api/transaction-relaying.md#shard-routing) | | `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 ```javascript 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](/developers/relayer-api/transaction-relaying.md) — Relay-specific errors and shard routing * [Transaction Broadcasting](/developers/relayer-api/transaction-broadcasting.md) — Broadcast-specific errors * [Account Subscriptions](/developers/relayer-api/account-subscriptions.md) — Subscription topic errors * [README](/developers/relayer-api.md) — Connection limits and rate limit parameters --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.xoxno.com/developers/relayer-api/error-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.