Errors

Failures come from two places:

• The API returns a standard gRPC status — a code plus a human-readable message. The SDKs surface it verbatim.
• The margin program rejects a transaction with a custom program error code (custom program error: 0x…). You see these from Solana RPC, from SponsorshipService.SponsorTransaction, or in TxService.SubscribeTxStatus failure events.

Generated unary service calls need an explicit retry policy. Managed SDK components retry selected failures: authentication can refresh a session, streams can reconnect, and QuotingCore can resend the same signed transaction. See Rust SDK. Do not build a replacement transaction merely because a submission timed out.

gRPC status codes

The message string is for humans and may change; branch on the code.

Session-specific failures

Margin maker sessions last 6 hours and challenge nonces 30 seconds. AuthFlow in both SDKs refreshes ahead of expiry and runs Challenge → sign → Authenticate from scratch, so nonce expiry is not your concern. Sessions are not guaranteed to survive a server restart or a move to another node, though: a previously good token can start returning UNAUTHENTICATED. Treat that as a cue to re-authenticate once with auth.refresh() — on the AuthFlow in either SDK. The Rust maker Client's managed streams and session heartbeat already do this on UNAUTHENTICATED.

Reading errors

use tonic::Code;
 
match account.get_account(req).await {
    Ok(res) => { /* ... */ }
    Err(status) => match status.code() {
        Code::ResourceExhausted | Code::Unavailable => backoff_and_retry().await,
        Code::NotFound => { /* no such trader account */ }
        _ => return Err(status.into()),
    },
}

import { GrpcCode, statusCode } from "@superis-labs/flint-margin-user-client";
 
try {
  await account.getAccount({ traderId: { id: 42n } });
} catch (err) {
  switch (statusCode(err)) {
    case GrpcCode.ResourceExhausted:
    case GrpcCode.Unavailable:
      await sleep(backoff);
      break;
    case GrpcCode.NotFound:
      // no such trader account
      break;
    default:
      throw err;
  }
}

In Rust, generated service clients return tonic::Status; the SDK's own helpers (Client::connect, AuthFlow) return flint_client_core::CoreError, re-exported as each crate's Error. In TypeScript, every failure is a GrpcError with a numeric code; asGrpcError, statusCode, statusMessage, and responseMetadata narrow an unknown error safely.

Transaction outcomes

TxService.SubmitTx returns once the server has accepted the transaction — not when it lands. Follow it on SubscribeTxStatus:

Save the signature before dispatch. Require RPC status at confirmed or finalized commitment with err: null before reporting success. If the outcome is unknown, follow transaction recovery.

SponsorshipService.SponsorTransaction waits for confirmation and returns the signature; a transaction the sponsor won't sign or that fails comes back as INVALID_ARGUMENT with the reason.

Program error codes

The margin program's custom errors, as numbered in the IDL (decimal / hex). The program also logs the failing source location and, for some codes, the subject (trader, asset, or perp id) — read the transaction logs for the detail the code alone can't carry.

Both on-chain clients ship the enum: FlintError in flint_margin_onchain::errors (Rust, FromPrimitive), and FLINT_ERROR__* constants with isFlintError(...) / getFlintErrorMessage(...) in @superis-labs/flint-idl.

General

Margin and collateral

GetActionLimits and SimulateAction predict most of these before you sign — the limit's constraint names which one binds.

Perp orders

OrderService.PreviewOrder simulates an order against the current book and margin before you sign it.

Order-book upkeep

The permissionless prunePerpOrders and forceCancelPerpOrders instructions, usually run by keepers.

PnL and funding settlement

Liquidation, backstop, and loss socialization

Mostly relevant to keepers.

Delegates and passkeys

Admin, keeper, and protocol operations

You won't see these from trading or quoting flows.