Errors

​

Where errors appear

• Handshake / connection layer: the server may refuse the upgrade (HTTP error) or close the socket with a WebSocket close code.
• Protocol layer: the server acknowledges subscribe / unsubscribe with a *_response message. Failures are returned as status: "error" with a structured error object.

​

Protocol errors (subscribe/unsubscribe)

{
  "action": "subscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "status": "error",
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request contains invalid or missing parameters.",
    "hint": "Ensure 'params' matches the stream filters and that addresses are 20-byte hex strings with no 0x prefix.",
    "severity": "error",
    "retryable": false,
    "details": {
      "invalid_parameters": [
        { "name": "params.topic_zeros[0]", "reason": "invalid_format" }
      ]
    },
    "docs_url": "https://docs.blockdb.io/wss-reference/overview/errors"
  }
}

{
  "action": "unsubscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "status": "error",
  "error": {
    "code": "NOT_SUBSCRIBED",
    "message": "No active subscription exists for this chain_id + dataset_id on the connection.",
    "severity": "warning",
    "retryable": false
  }
}

​

Error object fields

​

WebSocket close codes

• See: WSS Error Codes
• Typical handling:
  • 1008 POLICY_VIOLATION: verify API key / scope, then reconnect.
  • 1013 TRY_AGAIN_LATER: treat as backpressure; back off and reduce subscriptions/filters.
  • 1011 INTERNAL_ERROR: retry with jitter; contact support if persistent.

​

Practical handling guidance

• If status: "error" and retryable: false: fix the request (usually chain_id, dataset_id, or params formatting).
• If status: "error" and retryable: true: retry with exponential backoff and jitter.
• If the socket closes: use the close code to decide whether to refresh credentials, reduce load, or retry later.

​

See also

• Quickstart
• Connection Management
• WSS Error Codes