Error Handling

This guide covers error handling in the Cadenza WebSocket API, including error response formats and error codes.

Error Response Format

When an RPC call fails, the response contains an error object:

{
  "code": 22016,
  "message": "Not found"
}

Field	Type	Description
code	number	Positive error code identifying the error type
message	string	Human-readable error message

Error Code Format

Error codes follow the format: 22XXX where:

• 22 indicates a Usecase (business logic) error
• XXX (three digits) represents the specific error

For example, 22016 breaks down as:

• 22 = Usecase component
• 016 = Not found error

---

Error Codes

Code	Message	Description
22000	Unknown error	General business logic error.
22001	Duplicate exchange	Exchange connection already exists.
22002	Duplicate exchange name	Exchange name already in use.
22003	Exchange account ID mismatch	Account ID mismatch during renewal.
22004	User name already exists	Username is already taken.
22005	Hash function failed	Failed to generate or verify hash.
22006	Invalid API key	API key is invalid or has insufficient permissions.
22007	Webhook trigger failed	Failed to trigger webhook event.
22008	Encryption failed	Failed to encrypt data.
22009	Exchange already deleted	Exchange connection was already deleted.
22010	Exchange already exists	Exchange connection already exists.
22011	Exchange type not supported	Exchange type is not supported.
22012	Invalid exchange name	Exchange name is invalid.
22013	Exchange not found	Exchange connection not found.
22014	Lock not acquired	Failed to acquire resource lock. Retry after a short delay.
22015	Invalid argument	Invalid argument for operation.
22016	Not found	Requested resource not found.
22017	Already exist	Resource already exists.
22018	Permission denied	Insufficient permissions for this operation.
22019	Operation unsupported	Operation not supported in current context.
22020	Exchange not supported	Exchange is not supported.
22021	Database failure	Database operation failed.
22022	Exchange timeout	Exchange operation timed out.
22023	Unauthorized	Not authorized for this operation.
22024	No valid exchange account	No valid exchange account found.
22025	Set priority fail	Failed to set operation priority.
22026	Unsupported route policy	Routing policy not supported.
22027	Prerequisite error	Prerequisite condition not met.
22028	Cache not hit	Data not found in cache.
22029	Bad request	Invalid client request.
22030	Pubsub client not set	Pub/sub client not configured.
22031	Timeout	Operation timed out.
22032	Invalid execution plan	Execution plan is invalid.

---

Handling Errors

Python Example

from centrifuge import Client, RpcError

async def safe_rpc_call(client: Client, method: str, params: dict):
    try:
        result = await client.rpc(method, params)
        return result.data
    except RpcError as e:
        print(f"RPC Error: code={e.code}, message={e.message}")

        # Handle specific error codes
        if e.code == 22016:  # Not found
            return None
        elif e.code == 22023:  # Unauthorized
            raise UnauthorizedError(e.message)
        else:
            raise

TypeScript Example

import { Centrifuge, RpcError } from 'centrifuge'

async function safeRpcCall(client: Centrifuge, method: string, params: object) {
  try {
    const result = await client.rpc(method, params)
    return result.data
  } catch (error) {
    if (error instanceof RpcError) {
      console.error(`RPC Error: code=${error.code}, message=${error.message}`)

      // Handle specific error codes
      if (error.code === 22016) {  // Not found
        return null
      }
    }
    throw error
  }
}

---

Best Practices

1. Always handle errors - Wrap RPC calls in try/catch blocks
2. Log error details - Include error code and message for debugging
3. Handle specific codes - Implement logic for expected error scenarios
4. Retry transient errors - Errors like 22014 (lock not acquired), 22031 (timeout) may be temporary
5. Avoid retrying permanent errors - Errors like 22016 (not found) won't resolve with retries