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.

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.

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.
7001	`RATE_LIMIT_EXCEEDED`	Request rate limits.
9001	`BALANCE_INSUFFICIENT_TOKEN`	The wallet holds less of a required token than the operation needs.

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
  ) {
    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. To deduplicate submissions across process boundaries, see Use idempotency keys.

Send

Bridge

Swap

Unified Balance

Onramp

Earn

Borrow

Error handling for Borrow

Handling errors

Input errors

Service errors

Other errors

Retry a failed operation

​Handling errors

​Input errors

​Service errors

​Other errors

​Retry a failed operation

Handling errors

Input errors

Service errors

Other errors

Retry a failed operation