Connection Errors

CosmJS surfaces errors at two levels: transport-level errors from the RPC client, and broadcast-level errors from transaction submission.

Transport-Level Errors

Scenario	Error
Connection refused	`Error` with `ECONNREFUSED` or `fetch failed`
HTTP status >= 400	`Error` with status code and response body
JSON-RPC error response	`Error` with serialized JSON-RPC error object
HTTP request timeout	`AbortError` from `fetch` (via `AbortSignal.timeout()`)
WebSocket handshake timeout	`Error("Connection attempt timed out after X ms")`
Missing URL protocol (HTTP)	`Error("Endpoint URL is missing a protocol. Expected 'https://' or 'http://'.")`
Missing URL protocol (WebSocket)	`Error("Base URL is missing a protocol. Expected 'ws://' or 'wss://'.")`

Broadcast Errors

When a signed transaction is submitted but rejected during CheckTx (for example, insufficient fees or an invalid signature), the client throws a BroadcastTxError:

import { BroadcastTxError } from "@cosmjs/stargate";

try {
  await client.signAndBroadcast(address, messages, fee);
} catch (error) {
  if (error instanceof BroadcastTxError) {
    console.error("Code:", error.code, "Codespace:", error.codespace, "Log:", error.log);
  }
  throw error;
}

Timeout Errors

When a transaction is submitted successfully but not included in a block before the timeout expires, the client throws a TimeoutError with the transaction hash:

import { TimeoutError } from "@cosmjs/stargate";

try {
  await client.signAndBroadcast(address, messages, fee);
} catch (error) {
  if (error instanceof TimeoutError) {
    console.error("Tx may still land. Hash:", error.txId);
  }
  throw error;
}

A TimeoutError does not mean the transaction failed — it may still be included in a later block. You can query for it later using client.getTx(error.txId).

Fire-and-Forget Broadcasting

If you don’t want to wait for block inclusion, use signAndBroadcastSync to get the transaction hash immediately after submission:

const txHash = await client.signAndBroadcastSync(address, messages, fee);

This avoids the polling loop and the TimeoutError entirely. Use it when your application handles confirmation tracking separately.

No Built-In Retry

Neither HttpClient nor HttpBatchClient retry failed requests. If your application needs retry logic for transient network errors, wrap the RPC client or implement retries at the application level.

CosmJS

Concepts

Guides

API Reference

Transport-Level Errors

Broadcast Errors

Timeout Errors

Fire-and-Forget Broadcasting

No Built-In Retry

Next Steps

Timeouts

Connect to a Chain

​Transport-Level Errors

​Broadcast Errors

​Timeout Errors

​Fire-and-Forget Broadcasting

​No Built-In Retry

​Next Steps

Timeouts

Connect to a Chain

Transport-Level Errors

Broadcast Errors

Timeout Errors

Fire-and-Forget Broadcasting

No Built-In Retry

Next Steps