Error Handling

Handle Client and Server SDK envelopes, retries, and terminal errors safely.

Finatic SDKs return structured failures. Check the envelope for the SDK you use before reading data, and keep credentials and raw broker payloads out of user-visible errors.

Client SDK envelope

The browser Client SDK returns success, error, and warning:

const result = await finatic.v1.listAccounts({ includeSyncStatus: true });

if (result.error) {
  console.error(result.error.code, result.error.message, result.error.status);
  return;
}

const accounts = result.success?.data ?? [];
for (const warning of result.warning ?? []) {
  console.warn(warning.message);
}

Server SDK envelopes

The Node and Python Server SDKs return data, errors, warnings, and traceId:

const result = await finatic.v1.listAccounts();

if (result.errors?.length) {
  console.error(result.traceId, result.errors);
  return;
}

const accounts = result.data ?? [];
for (const warning of result.warnings ?? []) {
  console.warn(warning);
}

Keep traceId in tenant-safe internal logs and support reports. Never log API keys, Connect tokens, webhook secrets, or raw provider credentials.

Common first-run errors

Code or status	Meaning	Action
Token 401 / expired	The one-time Connect token lived about 90 seconds	Mint a new token immediately before `FinaticConnect.init`
`SESSION_INVALID_STATE`	Connect is incomplete or no active grant exists	Complete Connect and wait for `account.grant.created`
`ACCOUNT_ID_TYPE_MISMATCH`	A tenant/company ID was used as `accountId`	Use the financial account ID from the grant event or `listAccounts`
403	The current grant or API key lacks access	Stop and repair authorization instead of retrying
404	The resource is absent or outside the authorized account	Verify identifiers and tenant ownership
422	Validation failed	Correct the request from returned field details
429	The rate limit was reached	Retry only a safe read after `Retry-After`

Bounded retries for safe reads

Retry only idempotent reads after transport failures, 429, or transient 5xx responses. Bound attempts, honor Retry-After, add jitter, and surface the final error.

const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);

async function listAccountsWithRetry(maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let result;

    try {
      result = await finatic.v1.listAccounts();
    } catch (transportError) {
      if (attempt === maxAttempts) throw transportError;
      await new Promise((resolve) =>
        setTimeout(resolve, 250 * 2 ** (attempt - 1)),
      );
      continue;
    }

    if (!result.error) return result.success?.data ?? [];

    const status = result.error.status;
    if (!status || !RETRYABLE_STATUS.has(status) || attempt === maxAttempts) {
      throw new Error(result.error.message);
    }

    const retryAfterSeconds = Number(result.error.details?.retry_after ?? 0);
    const backoffMs = Math.max(
      retryAfterSeconds * 1000,
      250 * 2 ** (attempt - 1),
    );
    await new Promise((resolve) =>
      setTimeout(resolve, backoffMs + Math.floor(Math.random() * 100)),
    );
  }

  throw new Error('Account read exhausted its retry budget');
}

Do not automatically retry order placement, modification, or cancellation with a new idempotency key. A timeout can happen after the broker accepted the command. Preserve the original key and reconcile order state before submitting another trade.

Readiness is asynchronous

account.grant.created confirms durable authorization. Initial account data may still be pending. Poll a bounded number of times or consume supported events, show a visible pending state, and finish with a timeout or error state instead of an infinite spinner.

Operational guidance

Translate technical failures into safe user-facing messages.
Log stable error codes, HTTP status, and traceId with tenant-safe context.
Never retry 401, 403, 404, or 422 without changing the request or authorization state.
Respect Retry-After and use bounded exponential backoff for safe reads.
Preserve idempotency keys while reconciling trading commands.
Alert on repeated terminal failures without exposing provider payloads or credentials.

Command Palette