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_API_KEY_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
TxnodError——Base 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_API_KEY_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_replayed—Thrown 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. Sustained exhaustion means waiting for open invoices to expire or release their addresses — the per-(project, chain) window is hard-capped at 19 derived addresses as a funds-safety guard (BIP-44 gap limit of 20), so raising poolSizePerChain beyond 19 has no effect.
TxnodOverlayMatchingModeErroroverlay_matching_mode_required_exact—Thrown by TxnodClient when the server returns error_code: overlay_matching_mode_required_exact.—
TxnodWebhookCapacityExhaustedErrorwebhook_capacity_exhausted503Thrown by TxnodClient when the server returns error_code: webhook_capacity_exhausted.Webhook fleet for this chain has no spare slots; retry_after_seconds is always 0 because partner retry alone won’t free capacity. Treat as a transient outage; queue the invoice and retry later.
TxnodServerErrorinternal_error500Thrown by TxnodClient when the server returns error_code: internal_error.Transient; retry with exponential backoff. Log request_id for support.
TxnodRateQuoteUnavailableErrorrate_quote_unavailable503Thrown by TxnodClient when the server returns error_code: rate_quote_unavailable.The rate provider is warming up or briefly unavailable (no fresh USD quote). Transient — wait retry_after_seconds (server-provided), then retry.
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.
TxnodEventNotResendableErrorevent_not_resendable—Thrown by TxnodClient when the server returns error_code: event_not_resendable.—
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_owned—Thrown by TxnodClient when the server returns error_code: wallet_not_owned.—
TxnodWalletHasActiveBindingsErrorwallet_has_active_bindings—Thrown by TxnodClient when the server returns error_code: wallet_has_active_bindings.—
TxnodSubscriptionExpiredErrorsubscription_expired—Thrown by TxnodClient when the server returns error_code: subscription_expired.—
TxnodTronNoActivatedAddressesErrortron_no_activated_addresses_available—Thrown by TxnodClient when the server returns error_code: tron_no_activated_addresses_available.—
TxnodTonOperatorWalletNotDeployedErrorton_operator_wallet_not_deployed—Thrown by TxnodClient when the server returns error_code: ton_operator_wallet_not_deployed.—
TxnodTonInvalidWalletVersionErrorton_invalid_wallet_version—Thrown by TxnodClient when the server returns error_code: ton_invalid_wallet_version.—
TxnodTonJettonResolveFailedErrorton_jetton_resolve_failed—Thrown by TxnodClient when the server returns error_code: ton_jetton_resolve_failed.—
TxnodTonCommentParseFailedErrorton_comment_parse_failed—Thrown by TxnodClient when the server returns error_code: ton_comment_parse_failed.—
TxnodTonConnectPayloadExpiredErrortonconnect_payload_expired—Thrown by TxnodClient when the server returns error_code: tonconnect_payload_expired.—
TxnodTonConnectPayloadUnknownErrortonconnect_payload_unknown—Thrown by TxnodClient when the server returns error_code: tonconnect_payload_unknown.—
TxnodTonConnectDomainMismatchErrortonconnect_domain_mismatch—Thrown by TxnodClient when the server returns error_code: tonconnect_domain_mismatch.—
TxnodTonConnectTimestampSkewErrortonconnect_timestamp_skew—Thrown by TxnodClient when the server returns error_code: tonconnect_timestamp_skew.—
TxnodTonConnectUnknownWalletVersionErrortonconnect_unknown_wallet_version—Thrown by TxnodClient when the server returns error_code: tonconnect_unknown_wallet_version.—
TxnodTonConnectSignatureInvalidErrortonconnect_signature_invalid—Thrown by TxnodClient when the server returns error_code: tonconnect_signature_invalid.—
TxnodTonConnectNetworkMismatchErrortonconnect_network_mismatch—Thrown by TxnodClient when the server returns error_code: tonconnect_network_mismatch.—
TxnodSandboxProjectRequiredErrorsandbox_project_required—Thrown by TxnodClient when the server returns error_code: sandbox_project_required.—
TxnodProductionProjectRequiredErrorproduction_project_required—Thrown by TxnodClient when the server returns error_code: production_project_required.—
TxnodSandboxPerOperatorCapReachedErrorsandbox_per_operator_cap_reached—Thrown by TxnodClient when the server returns error_code: sandbox_per_operator_cap_reached.—
TxnodSandboxKeyAgainstProductionProjectErrorsandbox_key_against_production_project—Thrown by TxnodClient when the server returns error_code: sandbox_key_against_production_project.—
TxnodProductionKeyAgainstSandboxProjectErrorproduction_key_against_sandbox_project—Thrown by TxnodClient when the server returns error_code: production_key_against_sandbox_project.—
TxnodSandboxProvisioningFailedErrorsandbox_provisioning_failed—Thrown by TxnodClient when the server returns error_code: sandbox_provisioning_failed.—
TxnodSandboxInvoiceTransitionInvalidErrorsandbox_invoice_transition_invalid—Thrown by TxnodClient when the server returns error_code: sandbox_invoice_transition_invalid.—
TxnodSandboxInvoiceNotFoundErrorsandbox_invoice_not_found—Thrown by TxnodClient when the server returns error_code: sandbox_invoice_not_found.—
TxnodSandboxInvoiceTerminalErrorsandbox_invoice_terminal—Thrown by TxnodClient when the server returns error_code: sandbox_invoice_terminal.—
TxnodSandboxRateLimitExceededErrorsandbox_rate_limit_exceeded—Thrown by TxnodClient when the server returns error_code: sandbox_rate_limit_exceeded.—
TxnodSandboxResetFailedErrorsandbox_reset_failed—Thrown by TxnodClient when the server returns error_code: sandbox_reset_failed.—
TxnodSandboxDeleteFailedErrorsandbox_delete_failed—Thrown by TxnodClient when the server returns error_code: sandbox_delete_failed.—
TxnodSandboxActiveInvoiceCapReachedErrorsandbox_active_invoice_cap_reached—Thrown by TxnodClient when the server returns error_code: sandbox_active_invoice_cap_reached.—
TxnodSandboxKeyInProductionErrorsandbox_key_in_production—Thrown 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_production—Thrown by TxnodClient when the server returns error_code: sandbox_xpub_in_production.—
TxnodTxNotFoundErrortx_not_found_or_incomplete—Thrown by TxnodClient when the server returns error_code: tx_not_found_or_incomplete.—
TxnodTxAlreadyAttributedErrortx_already_attributed—Thrown by TxnodClient when the server returns error_code: tx_already_attributed.—