A timeout means the result is unknown. It does not mean a quote, deposit or payment failed. Keep the original intent and transaction identity throughout recovery.
import { ApiError, isOutcomeUnknown } from '@witches-brew/easypath-sdk';
try {
const quote = await client.quote(params);
await journal.saveQuote(quote);
} catch (error) {
if (isOutcomeUnknown(error)) {
await journal.markUnresolved(); // retain the original attempt
} else if (error instanceof ApiError) {
// Display error.code; preserve any existing deposit and recovery record.
}
throw error;
}
Record the quote attempt before this block. A storage error after a successful quote must also
hold the attempt; it is not permission to quote again. isOutcomeUnknown describes API request
outcomes, not wallet errors or failures in your own persistence layer.
| Error | Meaning | Next step |
|---|---|---|
OutcomeUnknownError |
Quote/submit response was lost, malformed or inconsistent | Keep identity; reconcile |
ApiError with outcomeUnknown === true |
Quote/submit returned HTTP 5xx | Keep identity; reconcile even with a structured error body |
Other ApiError |
API returned a structured refusal | Show the code; assess the existing attempt before any new action |
ProtocolError |
A read returned an invalid response | Preserve state; reconcile through a valid response |
DepositMismatchError |
Solana bytes disagree with the quote | Do not sign or send them |
| Local validation error | Amount, asset or EVM request is invalid | Correct input/configuration |
API errors expose code, httpStatus, retryAfterSeconds and, for mutations, operation.
Quote and submit are never retried automatically. Retry-After is not permission to create a
replacement intent. Server 5xx responses are conservatively treated as unresolved mutations.
Store the quote, sender, network, attempt stage, original signed bytes or wallet transaction hash, and latest status sequence. Store signed bytes securely and never log them. Keep one active operation per intent across tabs, sessions and application workers.
On restart, read client.status(intentId) first. Continue with client.poll(intentId, { since: savedStatusSeq, signal }). Apply only newer sequences for the same intent. A disconnected
poll can be resumed; it neither cancels the swap nor authorizes another deposit.
| Interrupted step | Recovery |
|---|---|
| Quote, before receiving an intent ID | Hold the attempt for operator reconciliation. The public API has no idempotency key or customer intent-list endpoint. |
| Solana signing | Preserve the attempt; do not request a new signature unless absence of the original send is established. |
| Solana relay, with saved bytes | Check status and the original signature. An explicit retry sends identical saved bytes for the same intent. |
| EVM approval | Reconcile the original attempt/hash and receipt. Do not deposit while unresolved. |
| EVM deposit | Reconcile the original attempt/hash and intent. Do not send a replacement. |
| Status read | Resume reads for the same intent and discard older sequences. |
watch reconnects a bounded number of times and refreshes REST status on each connection.
poll uses long polling and surfaces read failures. The default 65-second request timeout
accommodates the API's 60-second long poll. Aborting tracking never cancels a swap.
settled, refunded, expired and failed end tracking. Only settled indicates a successful
settled swap. filled still awaits origin finality. A timer or empty transaction lookup is
never proof that signed or submitted bytes cannot land. PostgreSQL owns accounting.