Error Handling

import { MonacoCoreError } from "@0xmonaco/core";

try {
  await sdk.vault.deposit(assetId, amount);
} catch (error) {
  if (error instanceof MonacoCoreError) {
    console.error('Code:', error.code);           // Error code (e.g., "INVALID_CONFIG")
    console.error('Message:', error.message);     // Human-readable error message
    console.error('Suggestion:', error.suggestion); // Helpful fix suggestion
    console.error('Retryable:', error.retryable); // Whether retry might succeed
    console.error('Timestamp:', error.timestamp); // When error occurred
  }
}

import { InvalidConfigError } from "@0xmonaco/core";

try {
  await sdk.vault.deposit(assetId, amount);
} catch (error) {
  if (error instanceof InvalidConfigError) {
    console.error('Configuration issue:', error.field);
    console.error('Suggestion:', error.suggestion);

    // Common cases:
    if (error.field === 'account') {
      // Wallet has no account connected
      alert('Please connect your wallet');
    } else if (error.field === 'seiRpcUrl') {
      // Invalid or missing RPC URL
      console.error('Provide valid Sei RPC URL');
    }
  }
}

import { InvalidStateError } from "@0xmonaco/core";

try {
  const address = sdk.getAccountAddress();
} catch (error) {
  if (error instanceof InvalidStateError) {
    console.error('State issue:', error.message);
    console.error('Suggestion:', error.suggestion);
    // "Check that prerequisites are met before calling this method."

    if (error.message === 'Wallet client not set') {
      console.error('SDK initialized without wallet client');
    } else if (error.message === 'No account available') {
      console.error('Wallet not connected or account unavailable');
    }
  }
}

import { ValidationError } from "@0xmonaco/types";

try {
  await sdk.trading.placeLimitOrder(pairId, 'BUY', '-10', '100');
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(error.message);      // "Validation failed:\n  - quantity: ..."
    console.error(error.getErrors());  // { quantity: "..." } — field path → message, for forms
    console.error(error.issues);       // raw Zod issues
  }
}

import { APIError } from "@0xmonaco/core";

try {
  // A read: safe to auto-retry on a retryable error. For order create/replace,
  // see "Retrying order mutations safely" below — reconcile, don't blind-retry.
  await sdk.trading.getPaginatedOrders({ status: 'SUBMITTED' });
} catch (error) {
  if (error instanceof APIError) {
    console.error('API Error:', error.statusCode);
    console.error('Endpoint:', error.endpoint);

    // Check if retryable (safe here because the wrapped call is a read)
    if (error.retryable) {
      // retryAfter is in SECONDS (from the Retry-After header); default to 5s.
      console.log('Can retry after:', error.retryAfter ?? 5, 'seconds');
      // Implement retry logic (multiply by 1000 for setTimeout, which is ms)
    }

    // Handle specific status codes
    switch (error.statusCode) {
      case 400:
        console.error('Bad request:', error.message);
        break;
      case 401:
        console.error('Unauthorized - please login');
        await sdk.login(clientId);
        break;
      case 429:
        console.error('Rate limited - wait before retrying');
        break;
      case 500:
        console.error('Server error - retry may help');
        break;
    }
  }
}

import { ContractError } from "@0xmonaco/core";

try {
  await sdk.vault.deposit(assetId, amount);
} catch (error) {
  if (error instanceof ContractError) {
    console.error('Contract error:', error.revertReason);
    console.error('Contract:', error.contractAddress);
    console.error('Transaction:', error.transactionHash);

    // Common issues:
    if (error.revertReason?.includes('insufficient allowance')) {
      console.log('Need to approve tokens first');
      await sdk.vault.approve(assetId, amount);
    }
  }
}

import { APIError } from "@0xmonaco/core";

try {
  await sdk.trading.cancelOrder(orderId);
} catch (error) {
  if (error instanceof APIError) {
    const body = (error.responseBody ?? {}) as { error?: string; code?: string; message?: string };
    console.error('Order rejected:', error.statusCode, body.code ?? body.error, body.message);

    if (error.statusCode === 404 || body.code === 'ORDER_NOT_FOUND') {
      console.log('Order already filled or cancelled');
    } else if (error.statusCode === 400 && body.message?.startsWith('Insufficient balance')) {
      console.log('Insufficient balance for this order');
    }
  }
}

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (error instanceof MonacoCoreError && error.retryable && attempt < maxRetries) {
        // `retryAfter` is in SECONDS — multiply by 1000 for setTimeout (ms).
        // Use `!== undefined` so a server-sent 0 (retry now) is honored rather
        // than falling through. Otherwise back off exponentially with jitter.
        const delayMs = error instanceof APIError && error.retryAfter !== undefined
          ? error.retryAfter * 1000
          : baseDelay * 2 ** (attempt - 1) + Math.random() * 1000;

        console.log(`Retry ${attempt}/${maxRetries} after ${Math.round(delayMs)}ms`);
        await new Promise(resolve => setTimeout(resolve, delayMs));
      } else {
        throw error; // Not retryable or max retries exceeded
      }
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage — wrap a read (or an idempotent mutation), never order create/replace:
const openOrders = await withRetry(() =>
  sdk.trading.getPaginatedOrders({ status: 'SUBMITTED', tradingPairId: pairId })
);

import { APIError } from "@0xmonaco/core";

async function retryWithRateLimit<T>(
  operation: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (error instanceof APIError) {
        if (error.statusCode === 429 && attempt < maxRetries) {
          // Rate limited - respect the Retry-After header. `retryAfter` is in
          // SECONDS; convert to ms for setTimeout. Default to 5s when absent.
          const delayMs = (error.retryAfter ?? 5) * 1000;
          console.log(`Rate limited. Waiting ${delayMs}ms...`);
          await new Promise(resolve => setTimeout(resolve, delayMs));
          continue;
        } else if (error.retryable && attempt < maxRetries) {
          // Other retryable error - exponential backoff with jitter.
          const delayMs = 1000 * 2 ** (attempt - 1) + Math.random() * 1000;
          await new Promise(resolve => setTimeout(resolve, delayMs));
          continue;
        }
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

import { APIError, type MonacoSDK } from "@0xmonaco/core";

// At startup — once, not per order. Register a durable handler and route events
// to whoever is waiting on a clientOrderId.
const pending = new Map<string, (orderId: string | null) => void>();
sdk.ws.userOrders((event) => {
  const coid = event.data?.clientOrderId;
  if (coid) pending.get(coid)?.(event.data.orderId ?? null);
});
// Wait for the connection before trading: registration alone does not prove the
// server-side subscription is active.

// Ambiguous = you never got a definitive response: network error, timeout, or a
// 5xx/409 with no order in the body. 401/429 are definitive rejections — auth is
// validated, and rate limits are applied, before the order reaches the book, so it
// was never placed and those may be resubmitted directly.
// The envelope carries TWO discriminators and they are different fields: `code` is the
// matching-engine code (CLIENT_ORDER_ID_CONFLICT), `error` is the API error type
// (OPERATIONS_BLOCKED). Read whichever the case needs.
function envelope(error: APIError): { code?: string; error?: string } {
  const body = error.responseBody;
  return typeof body === "object" && body !== null ? (body as { code?: string; error?: string }) : {};
}

function isAmbiguous(error: unknown): boolean {
  if (!(error instanceof APIError)) return true; // no HTTP status → assume ambiguous
  if (error.statusCode === 401 || error.statusCode === 429) return false;
  // A 409 is ambiguous EXCEPT when the engine names a deterministic conflict:
  // either code definitively rejects this submit, so there is nothing to reconcile.
  if (error.statusCode === 409) {
    return !["CLIENT_ORDER_ID_CONFLICT", "IDEMPOTENCY_KEY_CONFLICT"].includes(envelope(error).code ?? "");
  }
  // Maintenance is a deliberate pre-book rejection, not an ambiguous failure: the
  // order was blocked, never applied. Retry once the window ends.
  if (error.statusCode === 503 && envelope(error).error === "OPERATIONS_BLOCKED") return false;
  return error.statusCode === undefined || error.statusCode >= 500;
}

async function placeOrderReconciling(
  sdk: MonacoSDK,
  pairId: string,
  side: "BUY" | "SELL",
  quantity: string,
  price: string,
): Promise<string | null> {
  // Cheap precondition, NOT a guarantee: `isConnected()` reads local socket state
  // only (`readyState === OPEN`). The SDK sends Authenticate and Subscribe on open
  // and reports "connected" immediately, while the server activates the
  // subscription asynchronously — so this can pass before `orders` is live. It is
  // worth checking because a closed socket means no positive answer is possible at
  // all; it does not establish that one would reach you.
  if (!sdk.ws.isConnected()) {
    throw new Error("order stream not connected — refusing to place without it");
  }

  const clientOrderId = `quote-${crypto.randomUUID()}`;

  // Arm the matcher BEFORE sending, on the subscription established at startup,
  // and keep it armed for as long as the request is in flight. The stream is not
  // replayable, so a subscription opened after the failure cannot recover the
  // acknowledgement. Note there is no timer here: the SDK's fetch has no deadline
  // of its own, and a bounded wait started now could expire while the request is
  // still pending — disarming the matcher just before the event arrives.
  const landed = new Promise<string | null>((resolve) => {
    pending.set(clientOrderId, resolve);
  });

  try {
    const res = await sdk.trading.placeLimitOrder(pairId, side, quantity, price, {
      clientOrderId,
    });
    return res.orderId;
  } catch (error) {
    if (!isAmbiguous(error)) throw error; // definitively rejected — never applied

    // Ambiguous. Only NOW start the bounded wait, so the window measures how long
    // we wait for the acknowledgement rather than overlapping the request itself.
    const orderId = await Promise.race([
      landed,
      new Promise<null>((resolve) => setTimeout(() => resolve(null), 10_000)),
    ]);
    if (orderId) return orderId; // it landed — do NOT resubmit

    // No event. This is NOT evidence the order failed — the upstream fan-out can
    // be re-established without this socket changing state, so no observable
    // condition makes silence conclusive. Movement works one way only: an attributable position/balance change means
    // the order DID execute, so it blocks placing again — but unchanged state is
    // inconclusive and never clears you to place. If anything is unclear, hold and
    // surface the ambiguity rather than risking a double.
    return null;
  } finally {
    pending.delete(clientOrderId);
  }
}

const legs = [
  { tradingPairId: pairId, orderType: 'LIMIT', side: 'BUY', price: '35000.00', quantity: '0.5', idempotencyKey: crypto.randomUUID() },
  { tradingPairId: pairId, orderType: 'LIMIT', side: 'SELL', price: '36000.00', quantity: '0.3', idempotencyKey: crypto.randomUUID() },
];
const batch = await sdk.trading.batchCreate(legs);

console.log(`${batch.totalSucceeded}/${batch.totalRequested} created`);

batch.results.forEach((result, index) => {
  if (!result.error) return;
  if (result.error.code === 'SERVICE_UNAVAILABLE') {
    // Unknown outcome: reconcile first. If a retry is still needed, submit only
    // legs[index] so it carries the exact same explicit idempotencyKey.
    console.warn('Leg outcome unknown:', legs[index].idempotencyKey);
    return;
  }
  console.warn('Leg rejected:', result.error.code, result.error.message);
});

// If one side landed and the other failed you are one-sided: cancel the live legs
// (cancel is idempotent — safe to retry) or place the missing side before quoting.

try {
  const sdk = new MonacoSDK({ network: 'invalid-network', seiRpcUrl });
} catch (error) {
  if (error instanceof InvalidConfigError) {
    console.error('Error:', error.message);
    console.error('Suggestion:', error.suggestion);
    // Output:
    // Error: "network must be one of: mainnet, development, staging, local. Got: invalid-network"
    // Suggestion: "Check the 'network' configuration parameter. Valid networks are: 'mainnet', 'development', 'staging', 'local'."
  }
}

try {
  await sdk.vault.deposit(assetId, amount);
} catch (error) {
  if (error instanceof MonacoCoreError && error.suggestion) {
    // Show suggestion to user
    toast.error(`${error.message}\n\nSuggestion: ${error.suggestion}`);
  } else {
    toast.error(error.message);
  }
}

import {
  MonacoSDK,
  MonacoCoreError,
  InvalidConfigError,
  InvalidStateError,
  APIError,
  ContractError,
} from "@0xmonaco/core";
import { ValidationError } from "@0xmonaco/types";

async function placeOrderWithHandling(
  sdk: MonacoSDK,
  pairId: string,
  side: 'BUY' | 'SELL',
  quantity: string,
  price: string,
  attempt = 1
) {
  // Bound the retries so persistent ambiguity/auth/rate-limit can't recurse forever.
  if (attempt > 5) throw new Error('Max order-placement attempts exceeded');

  try {
    const order = await sdk.trading.placeLimitOrder(pairId, side, quantity, price);
    console.log('Order placed:', order.orderId);
    return order;

  } catch (error) {
    // Handle specific error types
    if (error instanceof InvalidConfigError) {
      console.error('Configuration error:', error.message);
      if (error.suggestion) {
        console.log('Fix:', error.suggestion);
      }
      throw error; // Can't recover from config errors

    } else if (error instanceof ValidationError) {
      // Rejected client-side before any request was sent — fix the parameters, do not retry.
      console.error('Invalid order parameters:', error.getErrors());
      throw error;

    } else if (error instanceof InvalidStateError) {
      console.error('State error:', error.message);
      throw error;

    } else if (error instanceof APIError) {
      console.error('API error:', error.statusCode, error.message);

      // 401 and 429 are DEFINITIVE rejections — the order never reached the book,
      // so re-authenticating / backing off and resubmitting cannot double-submit.
      if (error.statusCode === 401) {
        console.log('Re-authenticating...');
        await sdk.login('your-client-id');
        return placeOrderWithHandling(sdk, pairId, side, quantity, price, attempt + 1);
      } else if (error.statusCode === 429 && error.retryable) {
        // `retryAfter` is in SECONDS — convert to ms for setTimeout.
        const delayMs = (error.retryAfter ?? 5) * 1000;
        console.log(`Rate limited. Waiting ${delayMs}ms...`);
        await new Promise(resolve => setTimeout(resolve, delayMs));
        return placeOrderWithHandling(sdk, pairId, side, quantity, price, attempt + 1);
      } else if (error.retryable) {
        // AMBIGUOUS (network / timeout / 5xx / 409 with no order): the create MAY
        // already be live or filled. There is no safe automatic resubmit here.
        //
        // The order list CANNOT clear this: it is replica-backed, so a missing row
        // is not evidence the order did not land, and an order rejected
        // before acceptance is never written to it at all (one rejected after
        // acceptance is persisted with status REJECTED). Resubmitting on "no match" is the double-execution
        // path — see "Retrying order mutations safely" above.
        //
        // Resolve it on the order stream you subscribed to BEFORE sending, keyed on
        // a clientOrderId. A matching event settles it; silence does NOT, and no
        // observable condition makes silence meaningful. Absent positive evidence
        // the outcome stays unresolved: hold and escalate rather than placing again.
        console.warn('Ambiguous create — reconcile on the order stream; not resubmitting.');
        throw error;
      }
      throw error;

    } else if (error instanceof ContractError) {
      console.error('Contract error:', error.revertReason);
      if (error.revertReason?.includes('insufficient allowance')) {
        console.log('Approving tokens...');
        // Handle approval and retry
      }
      throw error;

    } else if (error instanceof MonacoCoreError) {
      // Generic MonacoCoreError handling
      console.error('SDK error:', error.code, error.message);
      if (error.suggestion) {
        console.log('Suggestion:', error.suggestion);
      }
      throw error;

    } else {
      // Unexpected error
      console.error('Unexpected error:', error);
      throw error;
    }
  }
}