Error handling for Borrow

The App Kit SDK surfaces failures as KitError instances with a BorrowError code. Errors fall into two Borrow categories:

Input errors (codes 1200-1299) signal that the request is invalid, stale, or references state that doesn’t exist. Fix the request and retry.
Service errors (codes 8200-8299) signal a backend or provider failure. Most are transient and safe to retry. A few are fatal, so check the table row before retrying.

Handling errors

The thrown KitError.name is prefixed with BORROW_ (for example, BORROW_LOAN_NOT_FOUND for the LOAN_NOT_FOUND code in the input errors table). Match on error.code, not on the raw name. Use the isInputError and isRetryableError helpers to branch:

TypeScript

import {
  BorrowError,
  isInputError,
  isRetryableError,
} from "@circle-fin/borrow-kit";

try {
  await kit.borrow.borrow(params);
} catch (error) {
  if (isInputError(error)) {
    if (error.code === BorrowError.IDEMPOTENCY_ALREADY_EXECUTED) {
      // The first submission already settled onchain. Treat as success.
    } else {
      // Fix the request: unknown market, standing authorization, etc.
    }
  } else if (isRetryableError(error)) {
    if (error.code === BorrowError.SIGNED_BUNDLE_EXPIRED) {
      // Signed execution expired. Resubmit with a new idempotencyKey.
    } else {
      await kit.borrow.retry(error);
    }
  } else {
    throw error;
  }
}

Input errors

Code	Name	When it fires
1200	`LOAN_NOT_FOUND`	`loanId` does not exist. A loan that has been wound down is still readable with `status: "closed"`. Writes against it raise `LOAN_NOT_OPEN` (1223).
1201	`INVALID_OWNER_SIGNATURE`	The owner signature is missing, expired, invalid, or does not bind the exact request.
1203	`INVALID_WEBHOOK_URL`	The webhook URL is missing, invalid, or fails a reachability probe against your endpoint.
1204	`INVALID_INPUT`	General validation failure with no more specific code.
1205	`UNSUPPORTED_CHAIN`	The blockchain is not supported for Borrow.
1206	`CONFIG_NOT_FOUND`	The caller has no integrator configuration yet. Expected before the first `setIntegratorConfig` call.
1207	`MARKET_NOT_FOUND`	The requested market does not exist, is not curated, or is disabled.
1208	`STANDING_AUTHORIZATION`	A previous authorization for this owner is still active on the underlying lending protocol. The kit grants and revokes authorization within a single batch and cannot borrow through a pre-existing standing grant. Revoke it on the underlying protocol before retrying.
1210	`IDEMPOTENCY_MISMATCH`	An `idempotencyKey` was reused with different request parameters.
1211	`WOULD_BE_UNHEALTHY`	A collateral withdrawal would leave the loan below `1.0` health. Only raised by `withdrawCollateralRepayIfNeeded`.
1212	`ALREADY_UNHEALTHY`	A collateral withdrawal was requested against a loan that is already liquidatable. Only raised by `withdrawCollateralRepayIfNeeded`.
1213	`SIGNED_BUNDLE_EXPIRED`	An `idempotencyKey` was replayed after its signed execution’s deadline. Retry with a new key.
1214	`LOAN_ALREADY_EXISTS`	A request to open a new loan named a market where the wallet already has one, or an earlier signed origination for the same wallet and market has not yet expired. Grow the existing loan by passing its `loanId`, or wait for the retry-after instant in the message.
1215	`IDEMPOTENCY_ALREADY_EXECUTED`	An `idempotencyKey` was replayed after its execution already settled onchain. Resolve the outcome from the prior execution rather than retrying.
1216	`WITHDRAWAL_EXCEEDS_COLLATERAL`	A collateral withdrawal asked for more than the loan has posted. Read the position’s `collateral` and withdraw at most that, or close the loan to release all of it.
1217	`REPAY_EXCEEDS_DEBT`	A repayment asked for more than the loan owes. Read the position’s `borrowed` amount and repay at most that, or use `closeLoan` to settle the debt in full.
1218	`INVALID_PAGE_CURSOR`	A `getLoans` `pageAfter` cursor fails to decode. Fetch a fresh first page rather than retrying the same cursor.
1219	`MAX_LOANS_EXCEEDED`	Opening this loan would exceed the configured maximum number of active loans, per wallet or in total.
1220	`INVALID_MARKET_SNAPSHOT`	The market’s onchain data snapshot is not in a valid state for this calculation (missing oracle price, LLTV, or borrow totals).
1221	`INVALID_INTEGRATOR_FEE`	The requested integrator fee rate is outside the permitted range (`0`–`10000` bps).
1222	`UNSUPPORTED_EXISTING_LOAN`	The wallet’s existing onchain loan in this market cannot have its prior history read on this blockchain, so opening it here is refused outright. Retrying will not help.
1223	`LOAN_NOT_OPEN`	The loan carries no debt, either because it was repaid or because it never borrowed. Borrow against it to open it before repaying, closing, or adding collateral.
1224	`INSUFFICIENT_COLLATERAL`	The wallet holds less collateral than the borrow needs. Post more collateral, or reduce the requested borrow amount, before retrying.
1225	`WEBHOOK_DEADLINE_OUT_OF_RANGE`	A `registerWebhook` signature’s `deadline` has already passed or is beyond the service’s accepted window. The signature itself may be valid. Reissue with a deadline inside the window.
1226	`LOAN_OPENING_PENDING`	A write or quote addressed a loan that is still opening. Its signed opening `borrow` hasn’t landed yet, or has landed and is still being processed. Wait, then retry.
1227	`LOAN_OPENING_EXPIRED`	The loan’s signed opening `borrow` expired without landing. Call `borrow({ loanId })` again to open the loan. Retrying the same request won’t help.
1228	`INSUFFICIENT_MARKET_LIQUIDITY`	The requested borrow exceeds what the market can currently lend. The error message names the requested and available amounts. Borrow at most the available amount.

Service errors

Code	Name	When it fires
8200	`INTERNAL_ERROR`	Internal service error. Retryable in most cases. Fatal when raised by `exploreMarketsIterator` pagination guards.
8201	`UNRECOGNIZED_RESPONSE_CHAIN`	The service returned a blockchain this SDK version cannot map. Update the SDK. Not retryable, surfaced as fatal.
8202	`REWARDS_FETCH_FAILED`	Failed to fetch reward data. Retryable.
8203	`LOAN_DATA_PENDING`	Required loan data is still being repaired. Retry shortly.
8204	`UPSTREAM_UNAVAILABLE`	An SDK dependency is temporarily unavailable. Retry shortly.
8205	`PAUSED`	Circle has paused this write. Other writes on the loan may still work. Retry later.

Other errors

Some Borrow failures surface with codes outside the BorrowError range:

Code	Name	When it fires
1098	`INPUT_VALIDATION_FAILED`	Client-side validation on the request.
4001	`RPC_ENDPOINT_ERROR`	The RPC endpoint failed. Usually retryable, but `FATAL` when it fails during submission.
7001	`RATE_LIMIT_EXCEEDED`	Request rate limits.
9001	`BALANCE_INSUFFICIENT_TOKEN`	The wallet holds less of a required token than the operation needs.
9002	`BALANCE_INSUFFICIENT_GAS`	The wallet can’t cover the gas for the operation. On Arc, `repay`, `closeLoan`, `withdrawCollateralRepayIfNeeded`, and `addCollateral` from an externally owned account (EOA) also raise it before sending when the wallet can’t cover the USDC the operation pulls plus the quoted gas.

Retry a failed operation

kit.borrow.borrow, kit.borrow.repay, kit.borrow.addCollateral, kit.borrow.withdrawCollateralRepayIfNeeded, and kit.borrow.closeLoan run through several phases before they confirm onchain, and kit.borrow.retry(error) resumes a failed operation from where it stopped. When the Circle-signed execution has not expired, retry submits it again instead of requesting a new one. An operation that already confirmed is refused, so a retry cannot accidentally open a second loan or pay a repayment twice.

TypeScript

try {
  await kit.borrow.borrow(params);
} catch (error) {
  if (
    isRetryableError(error) &&
    error.code !== BorrowError.SIGNED_BUNDLE_EXPIRED
  ) {
    await new Promise((resolve) => setTimeout(resolve, 30_000));
    const result = await kit.borrow.retry(error);
  }
}

SIGNED_BUNDLE_EXPIRED (1213) is marked retryable, but kit.borrow.retry resubmits the same signed execution and fails again. Handle it by calling the original operation with a new idempotencyKey instead. Wait before you call kit.borrow.retry. Some retryable failures need time to clear, such as a loan that is still opening (LOAN_OPENING_PENDING) or a pause of loan writes (PAUSED), which can last minutes or longer. Wait longer after each failed attempt. kit.borrow.retry refuses errors marked FATAL. A fatal failure during submission, such as an RPC_ENDPOINT_ERROR or a batch confirmation timeout, can mean the wallet already broadcast the batch. Check whether the earlier transaction landed before you start the operation again. To deduplicate submissions across process boundaries, see Use idempotency keys.

Send

Bridge

Swap

Unified Balance

Onramp

Earn

Borrow