Skip to main content

​
Where errors appear

BlockDB WSS errors can surface in two places:
  • 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)

If a request is invalid (bad parameters, auth scope, limits), you’ll receive a response message: 
{
  "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"
  }
}

​
Error object fields

The error object is a stable schema designed for both humans and machines.
​
code
string
Machine-readable error code.
​
message
string
Human-readable summary of what went wrong.
​
hint
string
Optional diagnostic hint that points to the most common fix.
​
severity
string
One of info, warning, error, critical.
​
retryable
boolean
Whether retrying the same operation can succeed (typically with backoff).
​
details
object
Optional structured metadata (e.g., invalid field list, limit values, allowed enums).
​
docs_url
string
Optional documentation link relevant to this error.

​
WebSocket close codes

Some failures are communicated by closing the WebSocket (especially auth/policy and backpressure).
  • 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