Timelock errors and recovery
Import TimelockSolverError, TimelockApprovalHttpError, and
parseTimelockErrorDetails from @symmio/trading-core.
TimelockSolverError extends SymmApiError, retaining the raw responseData, HTTP
status, URL, method, retry hint and original cause. Its details: TimelockErrorDetails
contains:
| Field | Meaning |
|---|---|
code: number | null | Numeric provider code, including unknown/zero values. |
knownCode?: TimelockErrorCode | Typed known code from 3700 through 3713. |
errorCategory: string | Provider category, used for unknown-code classification. |
errorMessage: string | Provider message. |
errorDetail?: string | Provider’s textual detail; the complete original body is also preserved in responseData. |
firstMissingSelector?: Hex | First selector mentioned by error 3711, for diagnostics only. |
parseTimelockErrorDetails(body: unknown): TimelockErrorDetails parses a raw response
using either code or error_code. A missing or zero code is not proof of success;
the approval/action parser still requires an actual valid success payload.
import { TimelockSolverError } from "@symmio/trading-core";
try {
await requestWithdrawal();
} catch (error) {
if (error instanceof TimelockSolverError) {
if (error.details.knownCode === 3711) {
// Display the diagnostic, then check the entire policy, not just one selector.
console.info(error.details.firstMissingSelector);
}
showError(error.details.errorMessage, error.details.errorCategory);
}
throw error;
}TimelockErrorCode covers approval codes 3700–3707, 3709, 3710 and instant-open
codes 3708, 3711–3713. For example 3703/3704 mean pending instant open/close prevents
approval; 3708 reports active approvals blocking an instant open; 3711 reports
incomplete policy. Provider detail is authoritative for the remaining conditions.
React normalization preserves this object as SymmioRequestError.timelock and
retains the original error as cause.
TimelockApprovalHttpError adds responseBody and names the failed public approval
transport. A transport error with status 0 is ambiguous, not proof of solver rejection.
Reconcile instead of repeating writes
requestTimelockApprovalchecks response expiry against the selected chain’s latest block timestamp, not the device clock. A response validation failure retains the raw response inSymmApiError.responseData(TIMELOCK_APPROVAL_RESPONSE_MISMATCH). If the post-response chain read fails, the code isTIMELOCK_APPROVAL_TIME_UNAVAILABLEandcauseretains that read error. No approval is requested again automatically. These locally generated errors have status0and an empty URL because a custom provider need not expose HTTP metadata; status0alone does not imply a lost response. The retained response is not a validated approval: verify its account, unlocker, calldata hash and on-chain expiry before any execution. Do not log its signature to third-party telemetry or request a replacement blindly.TimelockSetupConfirmationError.hashidentifies a submitted setup whose receipt or policy reread failed. Recover that hash; do not configure again blindly.EarlyWithdrawExecutionError.approvaland.callDataretain an issued approval after storage/submission failure. The React hook also retains.hashwhen receipt confirmation fails. Access this recovery wrapper through the normalized error’scause; its owncauseholds the underlying failure.useEarlyWithdrawpreserves the original normalized error kind and code, including relay failures and mined reverts.- The fallback schedule is separate from a Core withdrawal. Query its stored state, and reconcile pending transactions, before executing or cancelling.
- For instant opens, persist
PreparedInstantOpenbefore POST. Recover the original request identity; never rebuild automatically.
The SDK does not derive a safe recovery deadline from HTTP timeout plus
validitySeconds. Issuance time may be unknown. There is no automatic retry, fallback
switch, approval-status endpoint, or app-specific storage policy hidden in these APIs.
Classify an interrupted attempt
The framework-neutral recovery classifiers are exported for React and other consumers that need to decide whether an attempt may safely be cleared. They do not retry, submit, or mutate storage:
| Export | Result |
|---|---|
getTimelockRecoveryTransactionHash(error) | Returns a valid retained transaction hash, when present. |
hasTimelockSubmissionEvidence(error) | Detects a transaction hash, relay request ID, or idempotency key that requires reconciliation. |
isDefiniteGaslessSimulationRejection(error) | Matches an HTTP 400 SIMULATION_REVERTED only when no relay or transaction submission is evidenced. |
isDefiniteTimelockApprovalRejection(error) | Matches only documented provider rejection status/code pairs that did not issue a usable approval. |
isUnsubmittedTimelockWalletRejection(error) | Matches an explicit wallet rejection only when there is no evidence of relay or transaction submit. |
Use these as conservative classification helpers. When submission evidence exists, preserve the attempt and reconcile it rather than creating a second approval or relay.