> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error responses and WebSocket close codes for BlockDB WSS streams.

## 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:

<CodeGroup>
  ```json subscribe_response (error) theme={null}
  {
    "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"
    }
  }
  ```

  ```json unsubscribe_response (error) theme={null}
  {
    "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
    }
  }
  ```
</CodeGroup>

## Error object fields

The `error` object is a stable schema designed for both humans and machines.

<ResponseField name="code" type="string">
  Machine-readable error code.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable summary of what went wrong.
</ResponseField>

<ResponseField name="hint" type="string">
  Optional diagnostic hint that points to the most common fix.
</ResponseField>

<ResponseField name="severity" type="string">
  One of `info`, `warning`, `error`, `critical`.
</ResponseField>

<ResponseField name="retryable" type="boolean">
  Whether retrying the same operation can succeed (typically with backoff).
</ResponseField>

<ResponseField name="details" type="object">
  Optional structured metadata (e.g., invalid field list, limit values, allowed enums).
</ResponseField>

<ResponseField name="docs_url" type="string">
  Optional documentation link relevant to this error.
</ResponseField>

## WebSocket close codes

Some failures are communicated by closing the WebSocket (especially auth/policy and backpressure).

* See: [WSS Error Codes](/troubleshooting/error-codes/wss/home)
* 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](/wss-reference/overview/quickstart)
* [Connection Management](/wss-reference/overview/connection-management)
* [WSS Error Codes](/troubleshooting/error-codes/wss/home)