SDK error codes
The 6000-6999 range, grouped by category.
The SDK uses a dedicated range of numeric error codes from 6000 to 6999. SDK and session failures use onError. The 6800-6802 and 6900-6902 transaction outcomes use onComplete; see the sections below.
General (6000-6099)
| Code |
Name |
Description |
6000 |
SdkGenericError |
Catch-all for unexpected SDK errors |
6001 |
SdkJavaScriptError |
Unexpected JavaScript runtime error |
Session (6100-6199)
| Code |
Name |
Description |
6100 |
SdkSessionLoadFailed |
Failed to fetch session data from the API |
6101 |
SdkSessionExpired |
The payment session timed out |
6102 |
SdkSessionNotInitialized |
Session or component not yet initialized |
6103 |
SdkEnvironmentMismatch |
The session does not belong to the configured environment |
Card and tokenization (6200-6299)
| Code |
Name |
Description |
6200 |
SdkCardFieldsInvalid |
One or more hosted card fields failed validation |
6201 |
SdkCardTokenizationFailed |
Card tokenization request failed |
6202 |
SdkCardInitFailed |
Hosted card fields failed to initialize |
6203 |
SdkCardProcessingFailed |
Card payment API call failed |
ACH (6300-6399)
| Code |
Name |
Description |
6300 |
SdkAchFieldsInvalid |
ACH form fields failed validation |
6301 |
SdkAchProcessingFailed |
ACH payment API call failed |
EFT (6400-6499)
| Code |
Name |
Description |
6400 |
SdkEftProcessingFailed |
EFT payment API call failed |
Wallet (6500-6599)
| Code |
Name |
Description |
6500 |
SdkWalletError |
Error during Apple Pay or Google Pay flow |
6501 |
SdkWalletProcessingFailed |
Wallet payment API call failed |
Third-party SDK (6600-6699)
| Code |
Name |
Description |
6600 |
SdkThirdPartySdkLoadFailed |
Failed to load an external SDK the payment form depends on |
| Code |
Name |
Description |
6700 |
SdkFormValidationFailed |
General form validation failure |
6701 |
SdkBillingValidationFailed |
Billing address fields failed validation |
3D Secure (6800-6899)
3DS-specific codes are surfaced on declined card transactions via the transaction's resultCode - and correspondingly on the failure redirect URL's errorCode query parameter and the SDK's onComplete callback payload. They let merchants distinguish a 3DS-driven decline from a generic issuer decline or an unrelated SDK error. Only emitted when the session was initiated with formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902.
| Code |
Name |
Description |
6800 |
Sdk3dsAuthenticationFailed |
The issuer's ACS rejected the 3DS cardholder authentication (card auth failed, security failure, stolen card, suspected fraud, transaction not permitted, and so on). Hard decline - retrying the same card without 3DS is unlikely to succeed. |
6801 |
Sdk3dsAuthenticationUnavailable |
3DS authentication could not be completed due to an upstream technical issue (ACS timeout, directory server unreachable, unexpected ACS error). Retrying later may succeed; retrying without 3DS is only safe if merchant policy allows. |
6802 |
Sdk3dsNotEnrolled |
The card is not enrolled in 3DS . Retry with 3DS disabled - if allowed by merchant policy - may be attempted; approval is not guaranteed. |
Note that the 3DS codes arrive on onComplete as a declined transaction's resultCode, not on onError. See 3D Secure.
These codes separate an issuer decision from a gateway failure on a card payment made through the hosted payment form or the SDK. Like the 3DS codes, they arrive as a declined transaction's resultCode on onComplete, on the failure redirect URL's errorCode, and on the transaction itself. Every failed hosted-form payment reports success: false and a non-zero resultCode. It is recorded as a transaction that GET /transactions returns, and it sends sale.completed or auth.completed with the same resultCode. approvedAmount is 0.
| Code |
Name |
Description |
6900 |
SdkCardDeclined |
The issuer declined the card. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. |
6901 |
SdkCardGatewayError |
The gateway rejected or failed the payment because of validation or a gateway failure rather than an issuer decision. |
6902 |
SdkCardTokenMissing |
The gateway reported no failure but returned no payment token. |
resultText carries the decline reason in uppercase, or DECLINED or ERROR when the gateway gave no reason. Its formatting can vary: the same reason can appear as INSUFFICIENT FUNDS or INSUFFICIENT_FUNDS. Branch on responseCode, and use resultText for display rather than comparing its exact text. On 6901 and 6902, responseCode is usually 0; the transaction still failed.
The test cards let you produce each decline reason in the sandbox.
Payment method not enabled (2014)
2014 (PaymentMethodNotEnabled) is not in the SDK range: it comes from the API when the payment method is not enabled for the merchant. The SDK does not ask the customer to retry it.
- ACH - the payment is recorded as a failed transaction with
resultCode: 2014 and resultText: "ACH payments are not enabled for this merchant.". It arrives on onComplete with success: false, on the return URL as resultCode=2014&errorCode=2014, and in sale.completed.
- EFT - no transaction is recorded and no webhook is sent. The SDK reports
onError with code: 2014 and the message EFT payments are not enabled for this merchant.
- Token sale or authorization through the API - see Errors and rate limits.
Enable the payment method for the merchant, or offer the customer a different one.