# Code and Formats source: https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/codes-formats/index.md ## 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. Refer to the error `details` for additional information. | Check that the input sent is correct. | | 400 | `InvalidLoginToken` | Occurs if unattended login is attempted when it is 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 that the call is made with the correct client credentials, and the 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 the 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` | A call to the 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, and 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 Payment Service User (PSU)/Third Party Provider (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. | ## 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. | ## Payload Encryption Errors {#payload-encryption-errors} For more details go to [Payload Encryption](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/api-basics/payload-encryption/index.md)