Hydra
Docs

How to handle disconnections and errors robustly.

Reconnection & Errors

WebSocket connections can drop for many reasons — network interruptions, server restarts, API key revocation, rate limits. Build your client to handle these gracefully.

Use exponential backoff with jitter — don't hammer the server on reconnect.

class HydraClient {
  private ws: WebSocket | null = null
  private reconnectDelay = 1000
  private maxDelay = 60000

  constructor(private apiKey: string) {}

  connect() {
    this.ws = new WebSocket(
      `wss://api.hydra.fast/v1/stream?apiKey=${this.apiKey}`
    )

    this.ws.addEventListener('open', () => {
      this.reconnectDelay = 1000  // reset on successful connect
    })

    this.ws.addEventListener('message', (e) => {
      this.handleMessage(JSON.parse(e.data))
    })

    this.ws.addEventListener('close', (e) => {
      if (e.code === 1008) {
        // Unauthorized — API key is invalid, revoked, or expired
        console.error('API key rejected. Check your key and try again.')
        return  // don't auto-reconnect on auth failure
      }
      if (e.code !== 1000) {
        // Unexpected close — reconnect with backoff
        this._reconnect()
      }
    })
  }

  private _reconnect() {
    const delay = this.reconnectDelay + Math.random() * 1000
    this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxDelay)
    setTimeout(() => this.connect(), delay)
  }

  private handleMessage(msg: { type: string; data: unknown }) {
    if (msg.type === 'connected') {
      console.log('Connected, scopes:', (msg.data as any).scopes)
      return
    }
    // dispatch to your handlers
  }
}

API Key Errors

When your API key is invalid, revoked, or expired, the server sends an error message and then closes the connection with code 1008:

{
  "type": "error",
  "data": {
    "message": "Unauthorized — provide a valid API key via ?apiKey= or x-api-key header"
  }
}

Do not auto-reconnect on 1008 — the same key will be rejected again. Instead, generate a new key in the Platform dashboard.

Rate Limiting

Each IP is limited to 10 concurrent WebSocket connections. If you exceed this limit, the server rejects the upgrade with HTTP 429 before the WebSocket handshake completes.

If you hit this limit:

  1. Close unused connections before opening new ones.
  2. Reuse a single connection per application where possible.

Common Issues

Symptom Likely Cause Fix
Close code 1008 immediately API key invalid/revoked/expired Generate a new API key
HTTP 429 on connect Too many connections from your IP Close unused connections
No messages after connect API key has no scopes assigned Add scopes to your key in Platform
No messages on a specific type Key missing that scope Add the scope and reconnect
Pings stop arriving Network issue or server restart Reconnect with backoff

Server Maintenance

When the server is going into planned maintenance, it closes connections with code 1001. Reconnect with backoff after receiving this code.