> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/payment-sdk/error-codes.md).

# 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 |

## Form and validation (6700-6799)

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

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

{% hint style="info" %}
Note that the 3DS codes arrive on `onComplete` as a declined transaction's `resultCode`, not on `onError`. See [3D Secure](/hosted-payment-form/3d-secure.md#reading-the-outcome).
{% endhint %}

## Hosted-form gateway outcomes (6900-6999)

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

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

{% hint style="info" %}
`resultText` carries the decline 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.
{% endhint %}

The [test cards](/going-live/test-cards.md#declined) let you produce each decline reason in the sandbox.

## Related

* [Errors and rate limits](/get-started/errors-and-rate-limits.md) - the full error envelope and the other code ranges
* [Callback payloads](/payment-sdk/responses.md)