Errors

Every failure the SDK raises is an InteropError with a kind. Branch on the class, the kind or the hub’s code, never on a message.

The error classes

Class	`kind`	Thrown when	Fields
`HubError`	`hub`	the hub refused the call with its error envelope (HTTP 400), or the gateway in front of it refused the call in the same envelope, with a real HTTP status and an `EPX` code	see below
`HubUnavailableError`	`unavailable`	no usable answer: a network failure, a timeout, or an answer that is not the envelope (an HTML page, a bare status). A POST may still have been accepted	`reason` (`network`, `timeout`, `http-status`, `not-json`, `bad-envelope`), `status`, `requestId`
`ProxyError`	`proxy`	your own proxy refused the call (browser only)	`status`, `code` (`PXY…`, see Partner backend)
`WalletError`	`wallet`	the wallet refused or failed, or is on the wrong account or chain	`reason`: `rejected`, `unsupported`, `failed`, `wrong-account`, `wrong-chain`, `reverted`
`VetError`	`vet`	the pre-signing checks refused the quote. Nothing was signed or sent	`report`
`QuoteExpiredError`	`quote-expired`	the quote ran out of time before it could be used	`quoteId`
`ReviewRequiredError`	`review-required`	a fresh quote is worse than the one the user reviewed. Nothing was signed	`fresh`, `reviewed`
`OutcomeUnknownError`	`outcome-unknown`	an order submission’s answer was lost, even after the re-post. The order may exist	`quoteId`, `hubOrderId`, `transactionHash`
`RefundError`	`refund`	a refund cannot go ahead, or not yet (see Refunds)	`reason`, `retryAfterSec`
`InteropError`	`invalid-input`	you passed something the contract cannot accept: a value that is not a secret key given to `hubTransport`, a route not open to a project id, a `subject` outside the hub’s rule, a quote’s `recipient` or `sourceAccount` that cannot be an address on its chain, …	—
`InteropError`	`timeout`	a wait (for an order’s end, a receipt) ran out of time. Nothing is known to have failed	—
`InteropError`	`aborted`	your `AbortSignal` fired	—

All entry points share one copy of these classes, so instanceof works whichever entry point threw. isAbortError(error) is also true for a platform AbortError.

`HubError`

Field	Meaning
`code`	the hub’s or the gateway’s code: `EIN0008`, `EPX0080`…
`status`	the HTTP status: `400` for the hub’s own answers; `401`–`504` for the gateway’s refusals
`reference`	the field or the reason, when the hub names one: `amount`, `providerRefused`, `NOT_YET_REFUNDABLE`…
`params`	the code’s values (`error_params`), always an array
`hubMessage`	the English message: for logs, never for program logic
`requestId`	the answer’s request id. Quote it when you contact the hub team
`entries`	every entry of the answer’s `errors[]`; the first one decides
`category`	from the code’s block, the same for `EIN` and `EPX` codes: `terminal` (`0001`–`0049`), `availability` (`0050`–`0079`), `busy` (`0080`–`0099`); `framework` (`EMC…`) or `unknown`
`retryable`	`true` for the availability and busy blocks, except `EIN0050` with `params[0]` `upstreamAuth` (the hub’s own credential at its aggregator: only an operator clears it)
`retryAfterMs`	a rate limit’s back-off: `error_params[0]` of `EIN0080` and of the gateway’s `EPX0080` and `EPX0082`, else the gateway’s `Retry-After` header (the only back-off `EPX0081` carries)

Two getters sort the codes that are not about the request:

isCredentialRefused: the gateway refused your credential (401: EPX0001 a missing or malformed key, EPX0002 an unknown, revoked or expired one, EPX0008 or EPX0009 a malformed or unknown project id), or a page’s origin that is not on the project’s list (403, EPX0010). An operator matter: retrying cannot fix it, and refused credentials count toward the gateway’s lockout of the caller’s IP (EPX0081).
isClientBug: a framework code that means the request itself was malformed (CLIENT_BUG_CODES).

Every code is listed in the Error reference.

What to tell the user

adviseError(error) sorts any error the SDK throws into an action, who it is for, and a default message:

import { adviseError } from "@c8ntinuum/infinity-interop-sdk";

try {
  await client.executeQuote({ quote, wallets });
} catch (error) {
  const advice = adviseError(error);
  if (advice.audience === "operator") reportToYourTeam(error);
  showMessage(advice.message); // or your own copy, keyed by advice.action
}

`action`	From	What to do
`fix-request`	`EIN0001`, `EIN0003`	let the user correct the input
`change-amount`	`EIN0008` `providerRefused`	ask for another amount
`change-destination`	`EIN0008` `notFillable`	suggest another network or token
`change-pair`	`EIN0002`	offer only what the catalog lists
`no-route`	any other `EIN0008`	say there is no route right now
`requote`	`EIN0004`–`EIN0007`, `EIN0010`, `EIN0021`, `QuoteExpiredError`, `ReviewRequiredError`	get a new quote, and have the user review it
`resubmit`	a lost submission: `OutcomeUnknownError`, or an availability answer (`EIN` or `EPX`) while submitting	follow the order; never ask for a new signature
`check-status`	a `timeout` while following an order	point the user to the order’s status
`retry-later`	availability and busy codes, the gateway’s `EPX0050`–`EPX0079`, `HubUnavailableError`, a `ProxyError` other than 401 or 403, a refund that is not possible yet	retry in a moment (`retryAfterMs` when known)
`wait`	`EIN0080`, and the gateway’s rate limits `EPX0080`–`EPX0099`	wait `retryAfterMs`, then retry
`not-found`	`EIN0009`	the order may just not be observed yet: ask again shortly
`operator`	the gateway’s other refusals (`EPX0001`–`EPX0049`: a refused key, project id or origin, a route not open to the credential), client bugs and other `EMC` codes, `EIN0049`, `upstreamAuth`, a `ProxyError` 401 or 403	show a generic message, and alert your team
`wallet`	`WalletError`	the wallet did not complete it (`rejected`: the user cancelled)
`none`	anything else	a generic message

audience is operator for the codes that describe your key, your project, your origins or your client: the user only needs to hear that the service is unavailable. DEFAULT_ERROR_MESSAGES holds the default English copy. Pass the route when you know it: adviseError(error, { route: "orderOpenFor" }) reads availability answers and a HubUnavailableError as resubmit, because on a submission they say nothing about whether the order exists.

Retrying

What the SDK already does

Timeouts. Every transport waits a little longer than the gateway, so the gateway’s own answer ends a slow call: hubTransport and projectTransport wait 25 s on quotes, 12 s on reads and 15 s on submissions; proxyTransport waits 30 s, 15 s and 35 s, longer than your proxy.
Submissions. When an order submission’s answer is lost (a timeout, a dropped connection, the gateway’s EPX0050–EPX0053), the SDK looks the order up by its derived hub order id, then re-posts the same body once. See Lost answers.
Tracking. Status polls ride out availability and busy answers, waiting at least retryAfterMs.
Quotes. executeQuote re-quotes when too little time is left to sign. See How long a quote lives.
Catalog. When the hub cannot be reached, the last good copy is used.

Everything else throws once, and the rest is your call.

Your rules

retryable is true: back off and retry. On a rate limit (EIN0080, the gateway’s 429), wait retryAfterMs first.
isCredentialRefused is true: stop, and alert your operators. Check the key or project id, and the project’s origin list, in the hub dashboard. Don’t retry meanwhile: 20 refused credentials within a minute lock the caller’s IP out of every call for the rest of that minute (EPX0081).
A terminal code (0001–0049): never retry unchanged. Fix the input, or quote again.
Once the user has sent a transaction for a quote (the wrap-native and swap-token lanes), never quote again or ask them to sign again for it: the deposit is on chain. Follow the order instead, with client.findOrderByTx(sourceChain, transactionHash) if you lost its id.
A HubUnavailableError on a POST may have been accepted. For quotes, just ask again. For submissions, the SDK’s recovery has already run: an OutcomeUnknownError means follow the order.
Your own abort: do not retry.

In the browser

Through your proxy, the browser gets:

HubError for the hub’s refusals about the request, relayed unchanged, and for the gateway’s rate limits and outages (429, 5xx), with their status and Retry-After;
ProxyError for everything about your key or your proxy: the proxy never relays a refused key. It reports it to you (onError) and answers PXY0503, as it does for history while its subject canary fails; a client bug or another refusal about the integration is PXY0500;
HubUnavailableError when the proxy cannot be reached, and a ProxyError PXY0502 when the proxy cannot reach the hub.

With a project id, the browser gets the gateway’s refusals directly, as HubErrors with an EPX code and a real status: EPX0010 (403), for one, means the page’s origin is not on your project’s list. GET /orders, the one route not open to a project id, never gets that far: projectTransport refuses it before calling, with an InteropError (invalid-input).

Get started

Core concepts

Resources

API reference

SDK

SDK reference

The error classes

`HubError`

What to tell the user

Retrying

What the SDK already does

Your rules

In the browser

​The error classes

​HubError

​What to tell the user

​Retrying

​What the SDK already does

​Your rules

​In the browser

The error classes

`HubError`

What to tell the user

Retrying

What the SDK already does

Your rules

In the browser