# Data Connect Components SDK Error Handling
source: https://developer.mastercard.com/open-finance-us/documentation/errors/connect-components-errors/index.md
Data Connect Components SDK error handling follows a consistent and predictable model for how
Mastercard Data Connect Components represents and communicates errors to your integrations.
Note: The error handling described in this section applies only to the Data Connect Components SDK, not to Data Connect Full or Data Connect Lite. For a description of those errors, see the [Full Error List](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md).
The framework is designed to:
* Determine what occurred during a failed interaction
* Understand whether progress is possible
* Decide how, or whether, to proceed
This model intentionally separates error descriptions from behavior.
You should not infer handling or user action from the descriptive fields.
This document defines handling and behavioral principles. It does not prescribe UX, screen design, or final user-facing message copy.
## Canonical Error Object {#canonical-error-object}
All errors exposed by Data Connect Components adhere to the following
schema. Fields are intentionally divided into behavioral and descriptive
signals.
```json
{
"error_code": "string", // Stable identifier
"error_type": "string", // Descriptive
"resolution_state": "string", // Behavioral
"error_description": "string (optional)", // Descriptive
"suggested_user_message": "string (optional)" // Descriptive
}
```
### Field Semantics {#field-semantics}
| Field | Description |
|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `error_code` | Stable numeric identifier using the existing Mastercard [error codes](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md). |
| `error_type` | Indicates the general source context of the error. **Note:** Error source context does not imply recoverability or required user action. **Guidelines:** * Descriptive only * Non-behavioral * Does not determine retry logic, handling behavior, or required user action **Values:** * `USER_ACTION` * `FINANCIAL_INSTITUTION` * `CONNECTION_ISSUE` * `PARTNER_ERROR` * `UNEXPECTED_ERROR` For more information about these states, see [Error Type Values](https://developer.mastercard.com/open-finance-us/documentation/errors/connect-components-errors/index.md#error-type-values). |
| `resolution_state` | Defines the expected handling behavior for an error. You can rely on this field to determine how to proceed. **Note:** The required user action is signaled exclusively by `resolution_state`. **Guidelines:** * Authoritative behavioral signal * Each error maps to exactly one resolution state * Behavior must never be inferred from any other field **Values:** The error returns one of these resolution states: * `USER_ACTION_REQUIRED` * `TRANSIENT_WAIT` * ` TERMINAL_END` For more information about these states, see [Resolution State Values](https://developer.mastercard.com/open-finance-us/documentation/errors/connect-components-errors/index.md#resolution-state-values). |
| `error_description` | Human-readable explanation of what occurred. **Note:** This field is not suitable for end user display. This field is intended help you analyze and debug the issue. **Guidelines:** * For some errors, this field may not be present * Intended for transparency and troubleshooting * Not normalized or stable across retries * Don't use to infer handling behavior * May improve over time as error coverage expands |
| `suggested_user_message` | Informational text that you may adapt or replace. The messages are subject to change---while the message meaning will remain the same, the message itself may change to clarify the issue. All messages are passed through from our applications. You are responsible for ensuring that the messages are appropriate for your application. **Partner Responsibility:** * Suggested messages originate from Mastercard Data Connect hosted experiences and may not be appropriate for a partner experience. * Partners are responsible for reviewing, adapting, replacing, and validating message content for their own application and users. **Guidelines** * Informational and non-prescriptive * Non-contractual and subject to change to improve clarity * Not required to be displayed. We are constantly improving our error messaging and handling with Mastercard hosted Data Connect, which means these messages may change as we improve our experience. * Required user action is signaled exclusively by `resolution_state` |
Note: We are constantly improving our error messaging and handling with Mastercard-hosted Data Connect, which means these messages may change as we improve our experience.
#### Error Type Values {#error-type-values}
Each Error Type Value returned by Data Connect Components maps to one of the following sources.
| Error Type | Description |
|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `USER_ACTION` | Illustrative examples include: * Credentials must be corrected * A valid MFA response must be provided * The user must reauthenticate * The user must grant required permissions * The user must complete a required action at the financial institution |
| `FINANCIAL_INSTITUTION` | Illustrative examples include: * The financial institution is unavailable * The financial institution changed its authentication process * The financial institution blocked access * The financial institution introduced a CAPTCHA or another security requirement |
| `CONNECTION_ISSUE` | Illustrative examples include: * Network interruption * Timeout * Connection termination * Session expiration * Communication failure |
| `PARTNER_ERROR` | Illustrative examples include: * Invalid partner credentials or token * Invalid customer identifier * Malformed request * Missing required request data * Incorrect partner configuration |
| `UNEXPECTED_ERROR` | Illustrative examples include: * Processing failure * Parsing or extraction failure * Internal exception * Unknown technical error * Exceeding login attempts |
#### Resolution State Values {#resolution-state-values}
Each error returned by Data Connect Components maps to one of the
following handling states. Together, these states define all supported handling paths for Data Connect Components errors. You must not infer behavior outside of these definitions.
| Resolution State | Description |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `USER_ACTION_REQUIRED` | The end user must provide new or corrected input to proceed. **Handling:** * Progress is blocked until user action is taken * Retrying without action will not succeed * Corrected credentials or information must be collected from the user. Submitting the same information again will generally result in the same error. **Note:** For MFA-related errors, restarting the authentication flow will be required. Submitting a new MFA response without restarting the flow will continue to result in an error. * Action may occur within the flow or externally (for example, updating information at the financial institution) * Prompt the user according to the nature of the error **Examples:** * Invalid credentials * Incorrect MFA response * User explicitly declined consent * User must update settings or take action at their financial institution |
| `TRANSIENT_WAIT` | A temporary or unstable condition occurred. Retrying may succeed. **Note:** Restarting the authentication flow (including returning the user to login) is considered a system retry, not user remediation. You should consider limiting the number of retries, as resolving a `TRANSIENT_WAIT` error tends to require more time. Some scenarios, such as bad credentials, do require the user to provide updated input. **Handling:** * Retrying may succeed but is not guaranteed * Restarting the authentication flow is acceptable * No corrective user input is expected * Neutral, non-actionable messaging may be displayed **Retry Guidance:** * You should limit retry attempts to no more than three * You may implement stricter limits based on your UX **Examples:** * Temporary financial institution unavailability * Network or timing issues * Temporary platform or parsing errors |
| `TERMINAL_END` | A hard stop for the current session. Progress is not possible at this time. For some workflows you may direct the user to return after several hours or another day, but at that moment, a retry won't work. If a subsequent retry may be effective, you can craft your user message to direct the user to return at the appropriate interval. **Note:** Returning a user to login does not indicate user error. This distinction is intentional. **Handling:** * Immediately retrying will not succeed * Restarting the authentication flow is not useful * No corrective action exists for the user * You may offer alternative paths **Examples:** * Financial institution blocking or CAPTCHA condition that cannot be completed in the current authentication flow * Non-recoverable technical condition for the current authentication flow * Unknown technical condition for which the current authentication flow cannot continue * Unexpected system error |
### Handling Unknown or Unmapped Errors {#handling-unknown-or-unmapped-errors}
Not all errors may be fully mapped at any given point in time. The
following rules apply:
* All required fields are still present in the response
* A valid `resolution_state` is always returned
* Unknown errors default to a safe, retryable behavior (typically `TRANSIENT_WAIT`)
* Generic messaging may be used until classification is refined
As mappings improve, updates may be introduced. You should treat
these as part of normal model evolution.
## Best Practices {#best-practices}
Data Connect Components does not prescribe UX flows, retry timing
(beyond general guidance), or messaging strategy outside these
constraints.
**Do:**
* Use `resolution_state` as the single authoritative behavioral signal
* Treat authentication restart as a mechanical retry when `resolution_state` = `TRANSIENT_WAIT`
**Don't:**
* Infer required action from descriptive fields
* Assume recoverability or user remediation based on error origin
## Applied Examples {#applied-examples}
Note: The field values below demonstrate handling patterns based on current analysis. Descriptive values may change as categorization completes.
| Error Code | error_type | resolution_state | Notes |
|------------|-----------------------|----------------------|-----------------------------------------------------------------------------------|
| 50050 | UNEXPECTED_ERROR | TERMINAL_END | General unexpected error |
| 122 | UNEXPECTED_ERROR | TERMINAL_END | Unexpected error while attempting to retrieve data from the financial institution |
| 924/921 | FINANCIAL_INSTITUTION | TERMINAL_END | Unsupported CAPTCHA |
| 525 | FINANCIAL_INSTITUTION | TERMINAL_END | Support-only resolution |
| 959 | USER_ACTION | USER_ACTION_REQUIRED | External FI user action |
| 105 | CONNECTION_ISSUE | TRANSIENT_WAIT | Institution intermittently available |
| 10005 | PARTNER_ERROR | TERMINAL_END | Invalid request |
| 331 | USER_ACTION | USER_ACTION_REQUIRED | MFA session expired |