Skip to Content
SDKErrors

Errors

Every method on TxnodClient throws a subclass of TxnodError on a non-2xx response, and verifyWebhookSignature throws one of three dedicated subclasses on a bad signature. The base class carries the RFC 7807 problem-details envelope — error_code, status, request_id, and the raw body as raw — so partners can branch on the typed subclass or log request_id for support.

Handling pattern

import { TxnodClient, TxnodCoinNotEnabledError, TxnodError, TxnodPoolExhaustedError, TxnodRateLimitError, } from '@txnod/sdk'; const client = new TxnodClient({ projectId: process.env.TXNOD_PROJECT_ID!, apiSecret: process.env.TXNOD_API_SECRET!, }); try { await client.createInvoice({ external_id: 'order-1', amount_usd: 10, coin: 'btc', }); } catch (err) { if (err instanceof TxnodCoinNotEnabledError) { // actionable: point the user at a supported coin } else if ( err instanceof TxnodRateLimitError || err instanceof TxnodPoolExhaustedError ) { await new Promise((r) => setTimeout(r, err.retry_after_seconds * 1000)); // retry } else if (err instanceof TxnodError) { // generic TxNod error — log err.request_id console.error(err.error_code, err.request_id); } else { throw err; } }

All error classes

Classerror_codeHTTPWhen thrownHow to handle
TxnodErrorBase class — thrown by every TxnodClient method on a non-2xx response.Base class — narrow via instanceof TxnodError as a catch-all after checking specific subclasses.
TxnodSignatureFormatErrorauth_invalid401Webhook signature header is missing or malformed.Malformed/missing X-Txnod-Signature header; reject the webhook with 401.
TxnodHmacErrorsignature_invalid401Webhook signature does not match.HMAC mismatch on inbound webhook; reject with 401 and do not process the payload.
TxnodTimestampErrortimestamp_out_of_window401Webhook timestamp is outside the ±300-second window.skew_seconds reports clock drift; alert if chronically non-zero, then reject.
TxnodWebhookPayloadParseErrorinternal_error401Webhook body passed HMAC but is not valid JSON.
TxnodValidationErrorvalidation_error400Thrown by TxnodClient when the server returns error_code: validation_error.Inspect err.raw.errors for per-field issues and surface them to the caller.
TxnodInvalidCoinErrorinvalid_coin400Thrown by TxnodClient when the server returns error_code: invalid_coin.Map the user toward a supported coin from getRates().
TxnodInvalidXpubFormatErrorinvalid_xpub_format400Thrown by TxnodClient when the server returns error_code: invalid_xpub_format.Surface the chain-specific xpub format requirement to the operator.
TxnodInvalidWebhookUrlErrorinvalid_webhook_url400Thrown by TxnodClient when the server returns error_code: invalid_webhook_url.The dashboard rejects non-https and non-public URLs; fix the webhook URL.
TxnodAuthInvalidErrorauth_invalid401Thrown by TxnodClient when the server returns error_code: auth_invalid.Re-check TXNOD_PROJECT_ID and TXNOD_API_SECRET.
TxnodSignatureInvalidErrorsignature_invalid401Thrown by TxnodClient when the server returns error_code: signature_invalid.Outbound HMAC mismatch; inspect clock and secret, do not retry.
TxnodSignatureReplayedErrorsignature_replayedThrown by TxnodClient when the server returns error_code: signature_replayed.
TxnodTimestampOutOfWindowErrortimestamp_out_of_window401Thrown by TxnodClient when the server returns error_code: timestamp_out_of_window.Outbound timestamp outside ±300s window; check system clock.
TxnodKeySuspendedErrorkey_suspended403Thrown by TxnodClient when the server returns error_code: key_suspended.Operator suspended; do not auto-retry.
TxnodProjectSuspendedErrorproject_suspended403Thrown by TxnodClient when the server returns error_code: project_suspended.Project suspended; do not auto-retry.
TxnodPermissionDeniedErrorpermission_denied403Thrown by TxnodClient when the server returns error_code: permission_denied.API key lacks capability; surface to the operator.
TxnodKeyRevokedErrorkey_revoked403Thrown by TxnodClient when the server returns error_code: key_revoked.API key was rotated; fetch the new secret and redeploy.
TxnodInvoiceNotFoundErrorinvoice_not_found404Thrown by TxnodClient when the server returns error_code: invoice_not_found.Treat as 404 from the caller’s perspective.
TxnodProjectNotFoundErrorproject_not_found404Thrown by TxnodClient when the server returns error_code: project_not_found.Project id mismatch; surface to the operator.
TxnodWalletNotFoundErrorwallet_not_found404Thrown by TxnodClient when the server returns error_code: wallet_not_found.Chain wallet missing; register an xpub (see the Wallets guide).
TxnodExternalIdConflictErrorexternal_id_conflict409Thrown by TxnodClient when the server returns error_code: external_id_conflict.Idempotent replay — fetch the existing invoice via searchInvoices({ external_id }).
TxnodXpubNotVerifiedErrorxpub_not_verified409Thrown by TxnodClient when the server returns error_code: xpub_not_verified.Complete the index-0 handshake (see the Wallets guide).
TxnodCoinNotEnabledErrorcoin_not_enabled422Thrown by TxnodClient when the server returns error_code: coin_not_enabled.Enable the coin on the project or choose a different one.
TxnodAmountOutOfRangeErroramount_out_of_range422Thrown by TxnodClient when the server returns error_code: amount_out_of_range.Adjust amount_usd within project’s accepted range.
TxnodRateLimitErrorrate_limit_exceeded429Thrown by TxnodClient when the server returns error_code: rate_limit_exceeded.Back off for retry_after_seconds, then retry at most once.
TxnodPoolExhaustedErrorpool_exhausted503Thrown by TxnodClient when the server returns error_code: pool_exhausted.Hard-cap hit; wait retry_after_seconds (server-provided) before retrying, or raise poolSizePerChain if this fires under steady load.
TxnodServerErrorinternal_error500Thrown by TxnodClient when the server returns error_code: internal_error.Transient; retry with exponential backoff. Log request_id for support.
TxnodInvoiceNotCancellableErrorinvoice_not_cancellable409Thrown by TxnodClient when the server returns error_code: invoice_not_cancellable.Invoice in a terminal state; no action — the charge is final.
TxnodInvalidStateTransitionErrorinvalid_state_transition409Thrown by TxnodClient when the server returns error_code: invalid_state_transition.Re-read the invoice before retrying the state change.
TxnodOrphanNotFoundErrororphan_not_found404Thrown by TxnodClient when the server returns error_code: orphan_not_found.The tx hash either does not exist or belongs to another project.
TxnodOrphanAlreadyAttributedErrororphan_already_attributed409Thrown by TxnodClient when the server returns error_code: orphan_already_attributed.Look up the existing invoice via searchInvoices({ external_id }).
TxnodEventNotFoundErrorevent_not_found404Thrown by TxnodClient when the server returns error_code: event_not_found.Event id unknown or from another project.
TxnodWalletNotBoundErrorwallet_not_bound422Thrown by TxnodClient when the server returns error_code: wallet_not_bound.No verified wallet of matching kind is bound to the project for the requested chain. Bind one via the dashboard before retrying.
TxnodWalletKindMismatchErrorwallet_kind_mismatch422Thrown by TxnodClient when the server returns error_code: wallet_kind_mismatch.Cross-kind binding rejected — production projects only accept production wallets; testnet projects only accept testnet wallets.
TxnodWalletNotOwnedErrorwallet_not_ownedThrown by TxnodClient when the server returns error_code: wallet_not_owned.
TxnodWalletHasActiveBindingsErrorwallet_has_active_bindingsThrown by TxnodClient when the server returns error_code: wallet_has_active_bindings.
TxnodSubscriptionExpiredErrorsubscription_expiredThrown by TxnodClient when the server returns error_code: subscription_expired.
TxnodTronNoActivatedAddressesErrortron_no_activated_addresses_availableThrown by TxnodClient when the server returns error_code: tron_no_activated_addresses_available.
TxnodTonOperatorWalletNotDeployedErrorton_operator_wallet_not_deployedThrown by TxnodClient when the server returns error_code: ton_operator_wallet_not_deployed.
TxnodTonInvalidWalletVersionErrorton_invalid_wallet_versionThrown by TxnodClient when the server returns error_code: ton_invalid_wallet_version.
TxnodTonJettonResolveFailedErrorton_jetton_resolve_failedThrown by TxnodClient when the server returns error_code: ton_jetton_resolve_failed.
TxnodTonCommentParseFailedErrorton_comment_parse_failedThrown by TxnodClient when the server returns error_code: ton_comment_parse_failed.
TxnodTonConnectPayloadExpiredErrortonconnect_payload_expiredThrown by TxnodClient when the server returns error_code: tonconnect_payload_expired.
TxnodTonConnectPayloadUnknownErrortonconnect_payload_unknownThrown by TxnodClient when the server returns error_code: tonconnect_payload_unknown.
TxnodTonConnectDomainMismatchErrortonconnect_domain_mismatchThrown by TxnodClient when the server returns error_code: tonconnect_domain_mismatch.
TxnodTonConnectTimestampSkewErrortonconnect_timestamp_skewThrown by TxnodClient when the server returns error_code: tonconnect_timestamp_skew.
TxnodTonConnectUnknownWalletVersionErrortonconnect_unknown_wallet_versionThrown by TxnodClient when the server returns error_code: tonconnect_unknown_wallet_version.
TxnodTonConnectSignatureInvalidErrortonconnect_signature_invalidThrown by TxnodClient when the server returns error_code: tonconnect_signature_invalid.
TxnodTonConnectNetworkMismatchErrortonconnect_network_mismatchThrown by TxnodClient when the server returns error_code: tonconnect_network_mismatch.
TxnodSandboxProjectRequiredErrorsandbox_project_requiredThrown by TxnodClient when the server returns error_code: sandbox_project_required.
TxnodProductionProjectRequiredErrorproduction_project_requiredThrown by TxnodClient when the server returns error_code: production_project_required.
TxnodSandboxPerOperatorCapReachedErrorsandbox_per_operator_cap_reachedThrown by TxnodClient when the server returns error_code: sandbox_per_operator_cap_reached.
TxnodSandboxKeyAgainstProductionProjectErrorsandbox_key_against_production_projectThrown by TxnodClient when the server returns error_code: sandbox_key_against_production_project.
TxnodProductionKeyAgainstSandboxProjectErrorproduction_key_against_sandbox_projectThrown by TxnodClient when the server returns error_code: production_key_against_sandbox_project.
TxnodSandboxProvisioningFailedErrorsandbox_provisioning_failedThrown by TxnodClient when the server returns error_code: sandbox_provisioning_failed.
TxnodSandboxInvoiceTransitionInvalidErrorsandbox_invoice_transition_invalidThrown by TxnodClient when the server returns error_code: sandbox_invoice_transition_invalid.
TxnodSandboxInvoiceNotFoundErrorsandbox_invoice_not_foundThrown by TxnodClient when the server returns error_code: sandbox_invoice_not_found.
TxnodSandboxInvoiceTerminalErrorsandbox_invoice_terminalThrown by TxnodClient when the server returns error_code: sandbox_invoice_terminal.
TxnodSandboxRateLimitExceededErrorsandbox_rate_limit_exceededThrown by TxnodClient when the server returns error_code: sandbox_rate_limit_exceeded.
TxnodSandboxResetFailedErrorsandbox_reset_failedThrown by TxnodClient when the server returns error_code: sandbox_reset_failed.
TxnodSandboxDeleteFailedErrorsandbox_delete_failedThrown by TxnodClient when the server returns error_code: sandbox_delete_failed.
TxnodSandboxActiveInvoiceCapReachedErrorsandbox_active_invoice_cap_reachedThrown by TxnodClient when the server returns error_code: sandbox_active_invoice_cap_reached.
TxnodSandboxKeyInProductionErrorsandbox_key_in_productionThrown by TxnodClient when the server returns error_code: sandbox_key_in_production.
TxnodEnvironmentUnknownErrorauth_invalid401Sandbox API secret (sk_sandbox_*) detected but environment is unknown. Set the environment constructor option, TXNOD_ENVIRONMENT, or NODE_ENV.
TxnodSandboxXpubInProductionErrorsandbox_xpub_in_productionThrown by TxnodClient when the server returns error_code: sandbox_xpub_in_production.