Skip to Content
Symmio Trading-SDK — the SDK surface for builders on Arbitrum

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:

FieldMeaning
code: number | nullNumeric provider code, including unknown/zero values.
knownCode?: TimelockErrorCodeTyped known code from 3700 through 3713.
errorCategory: stringProvider category, used for unknown-code classification.
errorMessage: stringProvider message.
errorDetail?: stringProvider’s textual detail; the complete original body is also preserved in responseData.
firstMissingSelector?: HexFirst 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

  • requestTimelockApproval checks response expiry against the selected chain’s latest block timestamp, not the device clock. A response validation failure retains the raw response in SymmApiError.responseData (TIMELOCK_APPROVAL_RESPONSE_MISMATCH). If the post-response chain read fails, the code is TIMELOCK_APPROVAL_TIME_UNAVAILABLE and cause retains that read error. No approval is requested again automatically. These locally generated errors have status 0 and an empty URL because a custom provider need not expose HTTP metadata; status 0 alone 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.hash identifies a submitted setup whose receipt or policy reread failed. Recover that hash; do not configure again blindly.
  • EarlyWithdrawExecutionError.approval and .callData retain an issued approval after storage/submission failure. The React hook also retains .hash when receipt confirmation fails. Access this recovery wrapper through the normalized error’s cause; its own cause holds the underlying failure. useEarlyWithdraw preserves 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 PreparedInstantOpen before 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:

ExportResult
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.

Last updated on