Errors

The SDK exposes two error classes:

OstiumError for client creation, transaction building, signing, submission, and contract interaction
OstiumSubgraphError for subgraph reads, builder API reads, parsing, and stream-related data lookups

OstiumError

OstiumError is thrown by the main OstiumClient surface.

import { OstiumError, OstiumErrorCode } from '@ostium/builder-sdk';

try {
  await client.openTrade(params);
} catch (error) {
  if (error instanceof OstiumError) {
    console.error(error.code, error.message);
  }
}

Error codes

Code	Meaning
`INVALID_CONFIG`	The client was created with incompatible or missing configuration for the selected mode.
`VALIDATION_FAILED`	Input parameters failed SDK validation before submission.
`ALLOWANCE_INSUFFICIENT`	The trader does not have enough USDC allowance for the requested action.
`SUBMISSION_FAILED`	Transaction or user operation submission failed.
`DELEGATION_FAILED`	Delegation setup is missing or the requested delegated action is not allowed in the current mode.
`CONTRACT_ERROR`	A contract read or write failed.
`NETWORK_ERROR`	An RPC or network request failed.
`SUBMISSION_PENDING`	The operation was submitted but its outcome is unknown. See below.

OstiumSubmissionPendingError

OstiumSubmissionPendingError extends OstiumError with code SUBMISSION_PENDING. It is thrown when an operation reached the network but the SDK could not confirm how it ended — in practice, when waiting for a gasless UserOperation receipt times out after 120 seconds. This is not a failure: the operation was accepted and can still land, so retrying risks opening the position twice. Reconcile instead of resubmitting:

import { OstiumSubmissionPendingError } from '@ostium/builder-sdk';

try {
  await client.openTrade(params);
} catch (error) {
  if (error instanceof OstiumSubmissionPendingError) {
    console.warn('still in flight:', error.userOpHash);
    // poll for the receipt, or reconcile against getOpenPositions()
    return;
  }
  throw error;
}

A gasless trade that reverts on-chain raises OstiumError with code CONTRACT_ERROR, naming the contract error — it is never reported as a success.

OstiumSubgraphError

OstiumSubgraphError is thrown by read methods backed by the subgraph or builder API.

import { OstiumSubgraphError, OstiumSubgraphErrorCode } from '@ostium/builder-sdk';

try {
  const positions = await client.getOpenPositions({ user: '0xTraderAddress' });
} catch (error) {
  if (error instanceof OstiumSubgraphError) {
    console.error(error.code, error.message);
  }
}

Error codes

Code	Meaning
`INVALID_CONFIG`	The read client was created with invalid endpoint or mode configuration.
`INVALID_PARAMS`	The read method was called with invalid arguments.
`FETCH_FAILED`	The subgraph or builder API request failed.
`NOT_FOUND`	A requested entity or pair could not be found.
`PARSE_ERROR`	The SDK received data but could not parse it into the expected shape.

Recommended handling

Catch OstiumError around trade setup and write methods.
Catch OstiumSubgraphError around read methods and streams.
Log both error.code and error.message.
If present, inspect error.cause for the underlying RPC, contract, or fetch error.

SDK

Client Modes

Helpers

Previews & Limits

Read Methods

Live State

Write Methods

Builder API

Builder

Trader

Legacy

OstiumError

Error codes

OstiumSubmissionPendingError

OstiumSubgraphError

Error codes

Recommended handling

​OstiumError

​Error codes

​OstiumSubmissionPendingError

​OstiumSubgraphError

​Error codes

​Recommended handling

OstiumError

Error codes

OstiumSubmissionPendingError

OstiumSubgraphError

Error codes

Recommended handling