Error Handling & Reconnect

Handle server errors, stream failures, and connection drops in Titan Direct integrations.

Titan Direct is a persistent WebSocket connection. Connections drop, tokens expire, and streams end unexpectedly. This guide covers every failure mode and how to build a reconnect loop that keeps your integration running.

Server messages

The server sends one of four message types — Response, Error, StreamData, or StreamEnd. See Types Reference for the full type definitions.

Server errors

When a request fails, the server sends an Error instead of a Response. Check for the Error key in every message handler:

ws.on('message', async (raw: Buffer) => {
  const msg = await decodeMessage(raw);

  if ('Error' in msg) {
    const { code, message, requestId } = msg.Error;
    console.error(`Request ${requestId} failed — code ${code}: ${message}`);
    return;
  }
});

Stream errors

A stream can end abnormally. StreamEnd carries an optional errorCode and errorMessage — if present, the stream did not terminate cleanly:

ws.on('message', async (raw: Buffer) => {
  const msg = await decodeMessage(raw);

  if ('StreamEnd' in msg) {
    const { id, errorCode, errorMessage } = msg.StreamEnd;

    if (errorCode !== undefined) {
      console.error(`Stream ${id} ended with error ${errorCode}: ${errorMessage}`);
      // Restart the stream or reconnect
    } else {
      console.log(`Stream ${id} ended cleanly`);
    }
  }
});

Connection drops

When the WebSocket closes, all active streams are dead. Listen for the close event and trigger your reconnect logic:

ws.on('close', (code: number, reason: Buffer) => {
  console.warn(`Connection closed — code: ${code}, reason: ${reason.toString()}`);

  if (code !== 1000) {
    // Abnormal close — reconnect
    scheduleReconnect();
  }
});

ws.on('error', (err: Error) => {
  console.error('WebSocket error:', err.message);
  // 'close' will fire after this
});

Token expiry

The server refuses connections where the JWT exp claim is in the past. If your connection is rejected immediately, check that your token is still valid before reconnecting:

function isTokenExpired(token: string): boolean {
  const [, payload] = token.split('.');
  const claims = JSON.parse(Buffer.from(payload, 'base64').toString());
  return Date.now() / 1000 > claims.exp;
}

Refresh your token before calling connect() if it's close to expiry.

Reconnect with exponential backoff

The SDK has no built-in reconnect — it's your responsibility. Here's a complete reconnect loop:

import WebSocket from 'ws';
import { Encoder, Decoder } from '@msgpack/msgpack';
import bs58 from 'bs58';
import { zstdCompress, zstdDecompress } from 'http-encoding';

const encoder = new Encoder({ useBigInt64: true });
const decoder = new Decoder({ useBigInt64: true });

const BASE_DELAY_MS = 1_000;
const MAX_DELAY_MS = 30_000;

let useCompression = false;

async function sendRequest(ws: WebSocket, id: number, data: Record<string, unknown>) {
  const encoded = encoder.encode({ id, data });
  ws.send(useCompression ? await zstdCompress(encoded) : encoded);
}

async function decodeMessage(raw: Buffer): Promise<any> {
  const data = useCompression ? await zstdDecompress(raw) : raw;
  return decoder.decode(data);
}

async function connect(): Promise<WebSocket> {
  const url = `${process.env.TITAN_ENDPOINT}?auth=${process.env.TITAN_JWT}`;

  return new Promise((resolve, reject) => {
    const ws = new WebSocket(url, [
      'v1.api.titan.ag+zstd',
      'v1.api.titan.ag',
    ]);

    ws.once('open', () => {
      useCompression = ws.protocol !== 'v1.api.titan.ag';
      resolve(ws);
    });
    ws.once('error', reject);
  });
}

async function runWithReconnect() {
  let attempt = 0;

  while (true) {
    try {
      const ws = await connect();
      console.log('Connected');
      attempt = 0; // reset backoff on success

      // Set up your message handler and streams here
      await setupStreams(ws);

      // Wait for connection to close
      await new Promise<void>((resolve) => ws.once('close', resolve));

    } catch (err) {
      attempt++;
      const delay = Math.min(BASE_DELAY_MS * 2 ** (attempt - 1), MAX_DELAY_MS);
      console.warn(`Reconnect attempt ${attempt} in ${delay}ms...`);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

async function setupStreams(ws: WebSocket) {
  let requestId = 0;

  // Call GetInfo first to confirm connection
  sendRequest(ws, requestId++, { GetInfo: {} });

  ws.on('message', async (raw: Buffer) => {
    const msg = await decodeMessage(raw);

    if ('Response' in msg && 'GetInfo' in msg.Response.data) {
      // Connection confirmed — open your streams
      openQuoteStream(ws, requestId++);
    }

    if ('Error' in msg) {
      console.error(`Error ${msg.Error.code}: ${msg.Error.message}`);
    }

    if ('StreamEnd' in msg && msg.StreamEnd.errorCode !== undefined) {
      console.error(`Stream error: ${msg.StreamEnd.errorMessage}`);
      ws.close(); // trigger reconnect
    }
  });
}

async function openQuoteStream(ws: WebSocket, id: number) {
  const SOL  = bs58.decode('So11111111111111111111111111111111111111112');
  const USDC = bs58.decode('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v');

  sendRequest(ws, id, {
    NewSwapQuoteStream: {
      swap: {
        inputMint: SOL,
        outputMint: USDC,
        amount: 1_000_000_000n,
        slippageBps: 50,
      },
      transaction: {
        userPublicKey: bs58.decode('YOUR_WALLET_PUBLIC_KEY'),
      },
    },
  });
}

runWithReconnect();

Stream IDs do not survive reconnects. After reconnecting, you must open a new stream — the previous stream ID is no longer valid.

Best practices

• Call GetInfo after every reconnect to confirm the server is reachable before opening streams.

• If a route has expiresAtMs or expiresAfterSlot set, check these before building a transaction — a quote valid when received can go stale by the time it lands on-chain.

• Keep your reconnect loop separate from your quote processing logic so a stream error doesn't silently kill the reconnect handler.

---

Related pages

• Stream & Execute a Swap — full guide with transaction building and error handling

• Error Codes — numeric error code reference

• Connection & Negotiation — protocol negotiation details

• Types Reference — ServerMessage, ResponseError, StreamEnd, and all type definitions