Error handling

Errors are gRPC statuses. The code tells you whether to retry; the message tells you why.

Code	Meaning	Retry
`INVALID_ARGUMENT`	The request is wrong.	No, not unchanged.
`UNAVAILABLE`	The operator cannot serve this right now.	Yes, with backoff.
`RESOURCE_EXHAUSTED`	Rate limited.	Yes, after the window.
`UNAUTHENTICATED`	Missing, unknown, or disabled credential.	No.
`NOT_FOUND`	No such quote, order, or token.	No.
`FAILED_PRECONDITION`	The request is fine but the state does not allow it.	No, not until the state changes.
`INTERNAL`	Operator-side failure.	Yes, sparingly.

Quote rejections

These come back as INVALID_ARGUMENT. The request needs to change before it will succeed.

Message	Cause
`unsupported pair`	That source and destination combination is not quotable. Same token to itself on one chain also lands here.
`invalid amount`	`amount_in` is not a positive decimal string in base units.
`invalid address`	`recipient` or `refund_address` is malformed for its chain.
`amount below minimum of N usd`	Trade size under the floor.
`amount above maximum of N usd`	Trade size over the ceiling.
`amount is too small to cover fees required for this order`	The committed fees would consume the whole deposit.
`invalid referrer list`	A referrer address is unusable, or the basis points are out of range.
`swap quotes unsupported on destination chain`	The destination has no aggregator configured for the requested token, or a same-chain swap was requested on Solana.
`gas drop exceeds the allowed maximum`	Over the chain’s `max_gas_drop`.
`gasless is not supported for this order`	`gasless: true` on a same-chain swap, a native source token, or a chain without gasless deposits.
`quote is not a source swap`	`GetSwapInstructions` was called for a quote with no source swap leg.

Temporary conditions

These come back as UNAVAILABLE. The same request may succeed shortly after, so retry with backoff rather than surfacing a hard failure.

Message	Cause
`quote disabled for chain`	Quoting is turned off for that chain right now.
`insufficient inventory`	Not enough float on the destination to cover the trade. Retrying smaller often works immediately.
`bridge pair suspended`	The cross-asset lane is paused, typically on a depeg or exposure limit.
`price unavailable`	The price feed is stale or missing for one of the assets.
`fee unbounded`	Fees could not be bounded, typically from missing gas data.
`aggregator error`	The routing aggregator failed or returned no route.

insufficient inventory is a size problem, not an outage. If your interface can suggest a smaller amount, that is a better response than an error.

Auth and limits

Message	Code	Fix
`unknown api key`	`UNAUTHENTICATED`	The key does not exist. Check for a copy error.
`api key disabled`	`UNAUTHENTICATED`	The key was revoked. Create a new one.
`rate limit exceeded`	`RESOURCE_EXHAUSTED`	Back off. Keyed limits are far higher than keyless ones.
`missing session token`	`UNAUTHENTICATED`	A `PartnerApi` call without a bearer token.
`invalid or expired session`	`UNAUTHENTICATED`	Sign in again.
`sponsor_fees requires an api key`	`UNAUTHENTICATED`	Send the request with your `x-api-key`.
`quote is not gasless`	`FAILED_PRECONDITION`	`SubmitGaslessOrder` for a quote not requested with `gasless: true`.
`insufficient funding balance`	`FAILED_PRECONDITION`	Top up through the partner panel or `BuildPartnerFunding`.

Retry policy

const RETRYABLE = new Set([Code.Unavailable, Code.ResourceExhausted]);

const withRetry = async <T,>(call: () => Promise<T>, attempts = 3): Promise<T> => {
  for (let i = 0; ; i++) {
    try {
      return await call();
    } catch (e) {
      if (i >= attempts - 1 || !RETRYABLE.has(ConnectError.from(e).code)) throw e;
      await new Promise((r) => setTimeout(r, 2 ** i * 500));
    }
  }
};

Retry reads freely. Do not retry GetQuote in a tight loop to force inventory to appear — it is rate limited and the answer will not change within a second.

Failures after the deposit

Once a deposit lands, nothing surfaces as an API error. Failure is expressed as order state instead: the order routes to a refund, or to one of the terminal failure states. Handle those in the tracking path, not in error handling. See Order lifecycle.

Reverts on chain

Revert	Cause
`InsufficientOutput`	A swap returned less than the committed minimum.
`AggregatorNotAllowed`	The aggregator in the calldata is not allowlisted. Refetch `GetSwapInstructions`.
`SwapFailed`	The aggregator call itself failed, usually stale routing calldata.
`InvalidMsgValue`	Transaction value does not match what the call expects.
`EnforcedPause`	The contract is paused.
`GasDropNotAllowed`	A gas drop was requested where it is not permitted.
`InvalidReferrerBps`	`referrerBps` on a same-chain swap is above the contract cap.

Stale swap calldata is the most common one. Fetch instructions immediately before sending, not at quote time.

Get started

Build a swap

Extend

Error handling

Quote rejections

Temporary conditions

Auth and limits

Retry policy

Failures after the deposit

Reverts on chain

​Quote rejections

​Temporary conditions

​Auth and limits

​Retry policy

​Failures after the deposit

​Reverts on chain

Quote rejections

Temporary conditions

Auth and limits

Retry policy

Failures after the deposit

Reverts on chain