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
| Class | error_code | HTTP | When thrown | How 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. |
TxnodSignatureFormatError | auth_invalid | 401 | Webhook signature header is missing or malformed. | Malformed/missing X-Txnod-Signature header; reject the webhook with 401. |
TxnodHmacError | signature_invalid | 401 | Webhook signature does not match. | HMAC mismatch on inbound webhook; reject with 401 and do not process the payload. |
TxnodTimestampError | timestamp_out_of_window | 401 | Webhook timestamp is outside the ±300-second window. | skew_seconds reports clock drift; alert if chronically non-zero, then reject. |
TxnodWebhookPayloadParseError | internal_error | 401 | Webhook body passed HMAC but is not valid JSON. | — |
TxnodValidationError | validation_error | 400 | Thrown by TxnodClient when the server returns error_code: validation_error. | Inspect err.raw.errors for per-field issues and surface them to the caller. |
TxnodInvalidCoinError | invalid_coin | 400 | Thrown by TxnodClient when the server returns error_code: invalid_coin. | Map the user toward a supported coin from getRates(). |
TxnodInvalidXpubFormatError | invalid_xpub_format | 400 | Thrown by TxnodClient when the server returns error_code: invalid_xpub_format. | Surface the chain-specific xpub format requirement to the operator. |
TxnodInvalidWebhookUrlError | invalid_webhook_url | 400 | Thrown by TxnodClient when the server returns error_code: invalid_webhook_url. | The dashboard rejects non-https and non-public URLs; fix the webhook URL. |
TxnodAuthInvalidError | auth_invalid | 401 | Thrown by TxnodClient when the server returns error_code: auth_invalid. | Re-check TXNOD_PROJECT_ID and TXNOD_API_SECRET. |
TxnodSignatureInvalidError | signature_invalid | 401 | Thrown by TxnodClient when the server returns error_code: signature_invalid. | Outbound HMAC mismatch; inspect clock and secret, do not retry. |
TxnodSignatureReplayedError | signature_replayed | — | Thrown by TxnodClient when the server returns error_code: signature_replayed. | — |
TxnodTimestampOutOfWindowError | timestamp_out_of_window | 401 | Thrown by TxnodClient when the server returns error_code: timestamp_out_of_window. | Outbound timestamp outside ±300s window; check system clock. |
TxnodKeySuspendedError | key_suspended | 403 | Thrown by TxnodClient when the server returns error_code: key_suspended. | Operator suspended; do not auto-retry. |
TxnodProjectSuspendedError | project_suspended | 403 | Thrown by TxnodClient when the server returns error_code: project_suspended. | Project suspended; do not auto-retry. |
TxnodPermissionDeniedError | permission_denied | 403 | Thrown by TxnodClient when the server returns error_code: permission_denied. | API key lacks capability; surface to the operator. |
TxnodKeyRevokedError | key_revoked | 403 | Thrown by TxnodClient when the server returns error_code: key_revoked. | API key was rotated; fetch the new secret and redeploy. |
TxnodInvoiceNotFoundError | invoice_not_found | 404 | Thrown by TxnodClient when the server returns error_code: invoice_not_found. | Treat as 404 from the caller’s perspective. |
TxnodProjectNotFoundError | project_not_found | 404 | Thrown by TxnodClient when the server returns error_code: project_not_found. | Project id mismatch; surface to the operator. |
TxnodWalletNotFoundError | wallet_not_found | 404 | Thrown by TxnodClient when the server returns error_code: wallet_not_found. | Chain wallet missing; register an xpub (see the Wallets guide). |
TxnodExternalIdConflictError | external_id_conflict | 409 | Thrown by TxnodClient when the server returns error_code: external_id_conflict. | Idempotent replay — fetch the existing invoice via searchInvoices({ external_id }). |
TxnodXpubNotVerifiedError | xpub_not_verified | 409 | Thrown by TxnodClient when the server returns error_code: xpub_not_verified. | Complete the index-0 handshake (see the Wallets guide). |
TxnodCoinNotEnabledError | coin_not_enabled | 422 | Thrown by TxnodClient when the server returns error_code: coin_not_enabled. | Enable the coin on the project or choose a different one. |
TxnodAmountOutOfRangeError | amount_out_of_range | 422 | Thrown by TxnodClient when the server returns error_code: amount_out_of_range. | Adjust amount_usd within project’s accepted range. |
TxnodRateLimitError | rate_limit_exceeded | 429 | Thrown by TxnodClient when the server returns error_code: rate_limit_exceeded. | Back off for retry_after_seconds, then retry at most once. |
TxnodPoolExhaustedError | pool_exhausted | 503 | Thrown 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. |
TxnodServerError | internal_error | 500 | Thrown by TxnodClient when the server returns error_code: internal_error. | Transient; retry with exponential backoff. Log request_id for support. |
TxnodInvoiceNotCancellableError | invoice_not_cancellable | 409 | Thrown by TxnodClient when the server returns error_code: invoice_not_cancellable. | Invoice in a terminal state; no action — the charge is final. |
TxnodInvalidStateTransitionError | invalid_state_transition | 409 | Thrown by TxnodClient when the server returns error_code: invalid_state_transition. | Re-read the invoice before retrying the state change. |
TxnodOrphanNotFoundError | orphan_not_found | 404 | Thrown by TxnodClient when the server returns error_code: orphan_not_found. | The tx hash either does not exist or belongs to another project. |
TxnodOrphanAlreadyAttributedError | orphan_already_attributed | 409 | Thrown by TxnodClient when the server returns error_code: orphan_already_attributed. | Look up the existing invoice via searchInvoices({ external_id }). |
TxnodEventNotFoundError | event_not_found | 404 | Thrown by TxnodClient when the server returns error_code: event_not_found. | Event id unknown or from another project. |
TxnodWalletNotBoundError | wallet_not_bound | 422 | Thrown 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. |
TxnodWalletKindMismatchError | wallet_kind_mismatch | 422 | Thrown 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. |
TxnodWalletNotOwnedError | wallet_not_owned | — | Thrown by TxnodClient when the server returns error_code: wallet_not_owned. | — |
TxnodWalletHasActiveBindingsError | wallet_has_active_bindings | — | Thrown by TxnodClient when the server returns error_code: wallet_has_active_bindings. | — |
TxnodSubscriptionExpiredError | subscription_expired | — | Thrown by TxnodClient when the server returns error_code: subscription_expired. | — |
TxnodTronNoActivatedAddressesError | tron_no_activated_addresses_available | — | Thrown by TxnodClient when the server returns error_code: tron_no_activated_addresses_available. | — |
TxnodTonOperatorWalletNotDeployedError | ton_operator_wallet_not_deployed | — | Thrown by TxnodClient when the server returns error_code: ton_operator_wallet_not_deployed. | — |
TxnodTonInvalidWalletVersionError | ton_invalid_wallet_version | — | Thrown by TxnodClient when the server returns error_code: ton_invalid_wallet_version. | — |
TxnodTonJettonResolveFailedError | ton_jetton_resolve_failed | — | Thrown by TxnodClient when the server returns error_code: ton_jetton_resolve_failed. | — |
TxnodTonCommentParseFailedError | ton_comment_parse_failed | — | Thrown by TxnodClient when the server returns error_code: ton_comment_parse_failed. | — |
TxnodTonConnectPayloadExpiredError | tonconnect_payload_expired | — | Thrown by TxnodClient when the server returns error_code: tonconnect_payload_expired. | — |
TxnodTonConnectPayloadUnknownError | tonconnect_payload_unknown | — | Thrown by TxnodClient when the server returns error_code: tonconnect_payload_unknown. | — |
TxnodTonConnectDomainMismatchError | tonconnect_domain_mismatch | — | Thrown by TxnodClient when the server returns error_code: tonconnect_domain_mismatch. | — |
TxnodTonConnectTimestampSkewError | tonconnect_timestamp_skew | — | Thrown by TxnodClient when the server returns error_code: tonconnect_timestamp_skew. | — |
TxnodTonConnectUnknownWalletVersionError | tonconnect_unknown_wallet_version | — | Thrown by TxnodClient when the server returns error_code: tonconnect_unknown_wallet_version. | — |
TxnodTonConnectSignatureInvalidError | tonconnect_signature_invalid | — | Thrown by TxnodClient when the server returns error_code: tonconnect_signature_invalid. | — |
TxnodTonConnectNetworkMismatchError | tonconnect_network_mismatch | — | Thrown by TxnodClient when the server returns error_code: tonconnect_network_mismatch. | — |
TxnodSandboxProjectRequiredError | sandbox_project_required | — | Thrown by TxnodClient when the server returns error_code: sandbox_project_required. | — |
TxnodProductionProjectRequiredError | production_project_required | — | Thrown by TxnodClient when the server returns error_code: production_project_required. | — |
TxnodSandboxPerOperatorCapReachedError | sandbox_per_operator_cap_reached | — | Thrown by TxnodClient when the server returns error_code: sandbox_per_operator_cap_reached. | — |
TxnodSandboxKeyAgainstProductionProjectError | sandbox_key_against_production_project | — | Thrown by TxnodClient when the server returns error_code: sandbox_key_against_production_project. | — |
TxnodProductionKeyAgainstSandboxProjectError | production_key_against_sandbox_project | — | Thrown by TxnodClient when the server returns error_code: production_key_against_sandbox_project. | — |
TxnodSandboxProvisioningFailedError | sandbox_provisioning_failed | — | Thrown by TxnodClient when the server returns error_code: sandbox_provisioning_failed. | — |
TxnodSandboxInvoiceTransitionInvalidError | sandbox_invoice_transition_invalid | — | Thrown by TxnodClient when the server returns error_code: sandbox_invoice_transition_invalid. | — |
TxnodSandboxInvoiceNotFoundError | sandbox_invoice_not_found | — | Thrown by TxnodClient when the server returns error_code: sandbox_invoice_not_found. | — |
TxnodSandboxInvoiceTerminalError | sandbox_invoice_terminal | — | Thrown by TxnodClient when the server returns error_code: sandbox_invoice_terminal. | — |
TxnodSandboxRateLimitExceededError | sandbox_rate_limit_exceeded | — | Thrown by TxnodClient when the server returns error_code: sandbox_rate_limit_exceeded. | — |
TxnodSandboxResetFailedError | sandbox_reset_failed | — | Thrown by TxnodClient when the server returns error_code: sandbox_reset_failed. | — |
TxnodSandboxDeleteFailedError | sandbox_delete_failed | — | Thrown by TxnodClient when the server returns error_code: sandbox_delete_failed. | — |
TxnodSandboxActiveInvoiceCapReachedError | sandbox_active_invoice_cap_reached | — | Thrown by TxnodClient when the server returns error_code: sandbox_active_invoice_cap_reached. | — |
TxnodSandboxKeyInProductionError | sandbox_key_in_production | — | Thrown by TxnodClient when the server returns error_code: sandbox_key_in_production. | — |
TxnodEnvironmentUnknownError | auth_invalid | 401 | Sandbox API secret (sk_sandbox_*) detected but environment is unknown. Set the environment constructor option, TXNOD_ENVIRONMENT, or NODE_ENV. | — |
TxnodSandboxXpubInProductionError | sandbox_xpub_in_production | — | Thrown by TxnodClient when the server returns error_code: sandbox_xpub_in_production. | — |