# Code and Formats source: https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-pay/codes-formats/index.md ## Failures {#failures} ### Failures within the login flow {#failures-within-the-login-flow} Did you experience that the [Connect Flow](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-pay/connect/connect-flow/index.md) is failing? It can happen if the end user has canceled the flow or if a bank-related error has occurred. In these cases, we redirect back to the provided `redirect_uri`, but we do not include the `code` and `consentId` query parameters. Therefore, if a request is made to the configured `redirect_uri` that does not include the `code` and `consentId` query parameters, it is safe to assume that the login flow was unsuccessful. In this case, you have to restart the flow from scratch. ### Failures outside of the login flow {#failures-outside-of-the-login-flow} It is also possible to experience failures during unattended logins in which the login to the bank is unsuccessful. In these cases, we send a [`ConnectionUpdateRequiredWebhook` webhook](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-pay/event-notifications/event-types/index.md#connectionupdaterequiredwebhook) to your configured webhook url. If this happens, we are not able to fetch new data from the end users' bank without the end users' help. To solve this, you need to start a [Manual Synchronisation](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-data/data-sync/index.md#manual-synchronization) which will require the end user to make a supervised login. After that, data synchronisation will be scheduled and automated data synchronizations will resume. ### Provide Rate Limiting {#provide-rate-limiting} One of the possible errors that can cause these failures, is the banks' rate limiting. As stated in PSD2 legislation, there is a limit of four logins per user per day. If we experience this happening, we send a [`ConnectionRateLimitedWebhook` webhook](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-pay/event-notifications/event-types/index.md#connectionratelimitedwebhook) to your configured webhook url which contains information about the affected consent and accounts, as well as the date the rate limiting will end. Attempts to do [Manual Synchronisation](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-data/data-sync/index.md#manual-synchronization) before the rate limiting ends will be ignored. ## Error handling {#error-handling} All successful requests to the API return HTTP 200. In case of errors, the API returns a JSON response containing the error code and details about the error: ```json { "error": "InvalidInput", "details": { "reason": "Unknown code", "validationErrors": { "Username": [ "Username is required" ], "Email": [ "Email must be at least 3 character long" "Email must be an email" ] } } } ``` The format and the keys of the error `details` varies between error codes. The following combination of error codes are returned from the API: | **HTTP Status** | **Reason Code** | **Description** | **How to handle** | |-----------------|-----------------------|---------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| | 400 | `InvalidInput` | Invalid input provided. See `details`. | Check that the input sent is correct. | | 400 | `InvalidLoginToken` | Occurs if unattended login attempted when it not supported, or if the login token has expired. | Only attempt unattended logins for login tokens that support it. | | 400 | `IncorrectToken` | Can occur for Login Tokens if they are malformed or invalid (during unattended login and auth/initialize.) | Ensure the call is made with the correct client credentials, and that token has not been malformed. | | 403 | `AccessDenied` | Authentication failed or session expired. The reason is specified in `details.reason`. | Check that the correct client credentials and access tokens are sent. Ensure the calls are not attempted after the session expires. | | 403 | `FeatureNotEnabled` | The feature is not enabled for the client. | Ensure you are using the correct client. Contact us if you want the feature to be enabled or believe it should be enabled for you. | | 403 | `ProviderDisabled` | The selected provider is currently disabled due to unresponsiveness or instability. | Check the [status page](https://status.aiia.eu) and retry the request later. | | 409 | `Conflict` | When retrying a request with the `X-Request-Id`-header present, where the first request has not yet finished. | Wait for the first request to finish or try again. | | 429 | `RateLimited` | Request exceeded rate limit. The limit and retry timeout are specified in `details.message`. | Wait for the specified time before retrying. | | 500 | `InternalError` | Unknown internal error. | | | 501 | `FeatureNotSupported` | The provider does not support the requested feature,for example payments or unattended login. | | | 503 | `ProviderCallFailed` | Call to provider failed. See details below. | | | 504 | `Timeout` | Call to provider timed out. | Call can be retried, but it is advisable to limit the amount of data retrieved. | The error code `ProviderCallFailed` is used when errors occur in integrations. These can happen for different reasons, so it is important to consider the reason code from `details.reason`. | **Reason Code** | **Description** | |---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `NetbankDown` | Occurs when the provider is having prolonged technical issues, or during service windows. Moderate retries are possible (exponential back-off, limited attempts). | | `UnknownError` | An unknown error occurred in the integration. Moderate retries are possible (exponential back-off, limited attempts). | | `RetrySession` | The session was terminated due to an intermittent error. Retrying a new session will most likely work. | | `Unauthorized` | The user unexpectedly became unauthorized within the session. For example if the user was logged out after signing in from another location. The session can be retried. | | `RateLimitExceeded` | When limits are hit for PSD2/RTS APIs within daily allowance for PSU/TPP. Access to the affected resources will be possible next day. | | `AdapterExpired` | The integration does not match the provider's API. Retry is not possible. This is exceptional and will be handled by our service. | #### List of reason codes {#list-of-reason-codes} Each state has more detailed information in the payment *reason codes*. Note: This list is not exhaustive and more reason codes may be added in the future if the need arises. Your integration should be able to support new (unknown) reason codes to prevent future incompatibilities. | **Main status code** | **Reason code** | **Description** | |----------------------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | `Requested` | `Requested` | The payment request was accepted by our service and the payment is ready to be performed by the payer. | | `InProgress` | `InProgress` | The payment initiation is currently in progress. | | `Authorized` | `Authorized` | The payment initiation was successfully authorized by the payer. | | `Initiated` | `Initiated` | The payment initiation was accepted by the bank. | | `Cancelled` | `Cancelled` | The Payer cancelled the payment. | | `InitiationNotConfirmable` | InitiationNotConfirmable | The payment initiation was successfully authorized by the payer, but we cannot retrieve the latest status with the bank anymore. | | `OnHold` | `OnHold` | The initiation of the payment was successfully authorized but the payment is OnHold. It requires further interaction from the payer. | | `Expired` | `AuthorizationTimeout` | The authorization for the payment has timed out. | | `Expired` | `LinkExpired` | The link for the payment request expired. | | `Failed` | `Rejected` | The Payer's bank rejected the payment. | | `Failed` | `BankUnavailable` | The bank is unavailable for payments due to technical issues. | | `Failed` | `AuthenticationMethodDisabled` | The chosen authentication method by the Payer is not supported. | | `Failed` | `NoPaymentAccounts` | There are no accounts available to pay from. | | `Failed` | `SourceAccountNotValidForPayments` | The account chosen can not be used to make a payment. | | `Failed` | `NotCustomerInBank` | The Payer is not a customer in the bank. | | `Failed` | `CredentialsNotAuthorizedToMakePayments` | The credentials used to authorize the payment do not have the rights to authorize a payment. | | `Failed` | `InvalidCurrency` | The currency of the account that the Payer selected does not match the currency of the payment. | | `Failed` | `DestinationNotSupported` | The currency of the account that the Payer selected does not match the currency of the payment. | | `Failed` | `Timeout` | Some process took too long and the payment has failed. | | `Failed` | `ValidationFailed` | There is an issue with how the integrator has made the integration. | | `Failed` | `TechnicalIssue` | Technical issue with the payment request. | ## Payment Errors {#payment-errors} When initiating payments, the provider may reject the payment or fail to process the request. If this happens, we return information in the `status.details` property of the payment response, for example: ```jsonc { "details": { "providerMessage": null, // Human readable message from the provider "errorType": "PaymentErrorType", // Overall error category, "errorCode": "InsufficientFunds" // Reason why the payment failed } } ``` The following errors can be returned from the API: | **Payment State** | **ErrorType** | **ErrorCode** | **Description** | |-------------------|-----------------------------------|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Cancelled` | `PaymentErrorType` | `AuthUrlExpired` | The payment was cancelled since the authorization url expired. | | `Unknown` | `PaymentErrorType` | `AuthUrlExpired` | The authorization link expired due to a timeout. | | `Cancelled` | `PaymentErrorType` | `TppCancelled` | The payment was cancelled following an explicit cancellation request. | | `Failed` | `LoginErrorType` | `AlreadyAuthenticated` | The session is already authenticated. | | `Failed` | `LoginErrorType` | `AuthenticationMethodDisabled` | Login failed because the selected method is disabled. | | `Failed` | `LoginErrorType` | `CredentialsBlocked` | Login failed due to the credentials being blocked by the provider. | | `Failed` | `LoginErrorType` | `ExternalAuthenticationTimeout` | Login failed due to an external timeout such as 2FA. | | `Failed` | `LoginErrorType` | `InvalidCredentials` | Login failed due to invalid credentials. | | `Failed` | `LoginErrorType` | `KeycardRenewalNeeded` | Login failed. Keycard must be renewed. | | `Failed` | `LoginErrorType` | `NetbankDown` | The bank infrastructure is currently unavailable due to maintenance or technical reasons. | | `Failed` | `LoginErrorType` | `NotCustomerInBank` | The user tried to login to a bank where they are not a customer. This can happen in countries using a national ID scheme where the login is successful, but the selected bank is not correct. | | `Failed` | `LoginErrorType` | `Timeout` | Login failed due to timeout. | | `Failed` | `LoginErrorType/PaymentErrorType` | `UnknownError` | An unexpected technical error occurred. | | `Failed` | `PaymentErrorType` | `BankServiceUnavailable` | The bank has technical issues with the payment service. Usually it has a 400+ http status code. | | `Failed` | `PaymentErrorType` | ` BankUnexpectedResponse` | The bank responded with an unexpected/incorrect message. | | `Failed` | `PaymentErrorType` | ` DestinationAccountInvalid` | The bank reported that the destination account number was invalid. | | `Failed` | `PaymentErrorType ` | `DestinationAccountNotValidForPayments` | The destination account is not valid for receiving payments. This only happens when a payment is between PSU-owned accounts. | | `Failed` | `PaymentErrorType` | `ExecutionDateOutOfRange` | The bank reported that execution date was out of range, such as too far in the future. | | `Failed` | `PaymentErrorType` | `ExecutionTypeNotAvailable` | It is not possible to perform the selected execution, for example where instant is not available. | | `Failed` | `PaymentErrorType` | `IdentifierInvalid` | A payment identifier was not accepted by the provider. | | `Failed` | `PaymentErrorType` | `InsufficientFunds` | The payment was rejected due to insufficient funds on the account. | | `Failed` | `PaymentErrorType` | `InvalidCurrency` | The currency of the chosen payment account did not match the payment initiation's currency. | | `Failed` | ` PaymentErrorType` | `MaximumAmountExceeded` | The payment amount is higher than the maximum allowed by the provider. Based solely on rules implemented by the provider. The can occur when a single payment has an amount that is too high, or when the accumulated total sum of payments over a period is too high. | | `Failed` | `PaymentErrorType` | `NoPaymentAccounts` | The user does not have access to any suitable accounts to pay from. | | `Failed` | `PaymentErrorType` | `PaymentNotFoundAtProvider` | The payment was not found at the provider. | | `Failed` | `PaymentErrorType` | `SourceAccountInvalid` | The user cannot use this source account for payments. | | `Failed` | `PaymentErrorType` | `Unauthorized` | The credentials used to authorize the payment do not have the rights to authorize a payment. | | `Failed` | `PaymentErrorType` | ` ValidationFailed` | An invalid value was provided when creating the payment and the payment initiation has been refused. | | `Pending` | `PaymentErrorType` | `OnHold` | The payment has been put on hold by the bank and cannot proceed without further interaction from the Payer. Instruct the Payer to check their netbank or contact their bank. | | `Unknown` | `PaymentErrorType` | `TokenExpired` | The token used to refresh the payment with the bank expired. | For payments, the global errors and reasons are mapped to `ErrorType` and `ErrorCode`, for example: | **ErrorType** | **ErrorCode** | **Description** | |----------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `ProviderCallFailed` | `Unauthorized` | The user unexpectedly became unauthorized within the session. For example, if the user was logged out after signing in from another location. The session can be retried. |