# 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](https://docs.xoxno.com/developers/relayer-api)                                          |
| `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](https://docs.xoxno.com/developers/relayer-api/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](https://docs.xoxno.com/developers/transaction-relaying#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](https://docs.xoxno.com/developers/relayer-api/transaction-relaying) — Relay-specific errors and shard routing
* [Transaction Broadcasting](https://docs.xoxno.com/developers/relayer-api/transaction-broadcasting) — Broadcast-specific errors
* [Account Subscriptions](https://docs.xoxno.com/developers/relayer-api/account-subscriptions) — Subscription topic errors
* [README](https://docs.xoxno.com/developers/relayer-api) — Connection limits and rate limit parameters