# Code and Formats source: https://developer.mastercard.com/open-finance-data/documentation/code-and-formats/index.md ## Error handling {#error-handling} Successful API responses return HTTP `200` or `201` if the response is immediate or HTTP `202` if the request has been accepted for asynchronous processing. In case of errors, the API returns a JSON response containing the error code and details about the failure: The following HTTP Status Codes will indicate that an API request failed to process successfully. ### HTTP Status Codes {#http-status-codes} | **HTTP Status Code** | **Description** | **Handling recommendations** | |-----------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 Bad Request | The server cannot process a request because it is malformed or invalid. | The body of the response will contain details about which properties are not valid or which business rule was not met. Fix the issue with the request before retrying. | | 401 Unauthorized | Missing or invalid authentication credentials. | Check that the access token you have provided is correct and not expired. | | 403 Forbidden | Access Denied | The request was valid, but you do not have permission to access the requested resource. Check consent scopes and client configuration. | | 404 Not Found | Requested resource does not exist. Verify the resource ID. | The requested resource (consent, account, transaction, etc.) does not exist. Verify the resource ID. | | 409 Conflict | Resource State Conflict | The requested operation conflicts with the current state of the resource (for example, attempting to use expired consent). | | 429 Too Many Requests | Rate Limit Exceeded | You have exceeded the rate limit for API calls. Wait for the rate limit window to reset (check the `X-RateLimit-Reset` header). | ##### Sample error {#sample-error} ```json { "Errors": { "Error": [ { "Source": "Open Finance Data API", "ReasonCode": "INVALID_INPUT", "Description": "Validation error occurred for the property: scopes", "Recoverable": false, "Details": "At least one scope is required." } ] } } ``` The `ReasonCode` field in the body of the error response indicates the type of error. | **Reason Code** | **Description** | **How to handle** | |----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `RESOURCE_NOT_FOUND` | This may occur on GET endpoints such as Get Consent, Get Connection, or Get Accounts. If the provided resource ID does not exist, it will respond with 404 Not Found. | Ensure the resource IDs you are using for the GET requests refer to valid entities previously created with a POST request. Verify consent IDs, connection IDs, and account IDs are correct. | ##### Example error code {#example-error-code} ```json { "Errors": { "Error": [ { "Source": "Open Finance Data API", "ReasonCode": "RESOURCE_NOT_FOUND", "Description": "Resource not found", "Recoverable": false, "Details": "The requested consent was not found." } ] } } ``` | **Reason Code** | **Description** | **How to handle** | |-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `INVALID_INPUT` | This applies primarily to POST endpoints such as Create Consent, Create Flow, and Update Flow that have request bodies. A 400 Bad Request response will be returned. The body of the response will contain details about which properties are not valid or which business rule was not met. | Fix the issue with the request before retrying. Common issues include missing required fields, invalid scope values, malformed redirect URLs, or incorrect PSU identifiers. | ##### Example error code {#example-error-code} ```json { "Errors": { "Error": [ { "Source": "Open Finance Data API", "ReasonCode": "INVALID_INPUT", "Description": "Validation error occurred for the property: scopes", "Recoverable": false, "Details": "Invalid scope value. Allowed values are: accounts, holders, balances, transactions." }, { "Source": "Open Finance Data API", "ReasonCode": "INVALID_INPUT", "Description": "Validation error occurred for the property: redirectUrl", "Recoverable": false, "Details": "The redirectUrl must be a valid HTTPS URL." } ] } } ``` | **Reason Code** | **Description** | **How to handle** | |------------------|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------| | `INTERNAL_ERROR` | An unexpected error occurred in the Open Finance Data platform. | Retry the request. If the issue persists, contact Customer Support with the correlation ID from the response headers. | ##### Example error code {#example-error-code} ```json { "Errors": { "Error": [ { "Source": "Open Finance Data API", "ReasonCode": "INTERNAL_ERROR", "Description": "An unexpected error has occurred with the service you have requested.", "Recoverable": false, "Details": null } ] } } ``` | **Reason Code** | **Description** | **How to handle** | |-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `RATE_LIMITED` | This occurs when you have exceeded your rate limit for the endpoint. A 429 Too Many Requests response will be returned. See Advanced Topics \> Rate Limiting in the API Reference. | Check the X-RateLimit-Reset header to see when the rate limit window resets and you can start making requests again. Implement exponential backoff for retry logic. | ##### Sample of the header received in this scenario {#sample-of-the-header-received-in-this-scenario} HTTP/1.1 429 Too Many Requests Date: Mon, 08 Jul 2024 09:27:06 GMT Status: 429 Too Many Requests X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 16 ##### Example error code {#example-error-code} ```json { "Errors": { "Error": [ { "Source": "Open Finance Data API", "ReasonCode": "RATE_LIMITED", "Description": "Too many requests", "Recoverable": true, "Details": null } ] } } ``` | **Reason Code** | **Description** | **How to handle** | |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `UNAUTHORIZED` | The provided authorization token is not valid. This may occur if the token has expired, the JWT assertion was invalid, or the client credentials are incorrect. | Check that the access token you have provided is correct and not expired. Verify your JWT creation and signing process. Ensure your client ID and certificate thumbprint (kid) are correctly configured. Request a new access token if the current one has expired. | ##### Example error code {#example-error-code} ```json { "Errors": { "Error": [ { "Source": "Open Finance Data API", "ReasonCode": "UNAUTHORIZED", "Description": "Unauthorized - Access Not Granted", "Recoverable": false, "Details": "Invalid or expired access token." } ] } } ``` | **Reason Code** | **Description** | **How to handle** | |-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `FORBIDDEN` | You do not have access to the requested resource. This may occur if you attempt to access data scopes not granted in the consent, or if your client configuration does not permit the requested operation. | Verify that the consent includes the required scopes for the data you are trying to access. Contact customer support if you believe your client should have access to this resource.. | ##### Example error code {#example-error-code} ```json { "Errors": { "Error": [ { "Source": "Open Finance Data API", "ReasonCode": "FORBIDDEN", "Description": "Access to the requested resource is forbidden", "Recoverable": false, "Details": "Consent does not include the required scope: balances" } ] } } ``` ### Failures in the Consent Flow {#failures-in-the-consent-flow} A webhook notification is returned when a consent status changes. Refer to the [Consent Lifecycle](https://developer.mastercard.com/open-finance-data/documentation/consent-management#consent-lifecycle/) documentation for a Consent Status Flow diagram and a description of possible statuses. Below are recommendations on how to handle failure or undefined states of the consent: | **Consent status** | **Handling recommendations** | |---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `CANCELLED` | The user cancelled the authorization flow. You may offer the user option to try again. | | `FAILED` | The consent authorization failed. This can occur for several reasons including the bank rejecting the consent, SCA failure, or user errors. For more information about the failure, refer to the details section of the response.​ | | `EXPIRED` | The consent has expired. For one-off consents, this is expected after data retrieval. For ongoing consents, you need to create a new consent and guide the user through authorization again. | | `REVOKED` | The user has revoked their consent. Respect the user's decision. If continued access is needed, request new consent with clear explanation of why it is necessary. | | `AUTHORIZATION_FLOW_INCOMPLETE` | The consent authorization URL expired, or the user left the authorization page without completing the flow. You may offer the user the option to try again with a new consent. | ### Failures in Data Retrieval {#failures-in-data-retrieval} A webhook notification is returned hen data retrieval status changes. Refer to the use case documentation for detailed flow diagrams and descriptions of possible statuses. Below are recommendations on how to handle failure or undefined states during data retrieval: | **Status** | **Handling recommendations** | |------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | `CONNECTION_EXPIRED` | The bank connection has expired. Prompt the user to reauthenticate with their bank using the reconnection flow. The consent remains valid. | | \`\`DATA_UNAVAILABLE\` | The requested data is not available from the bank. Check supported data scopes for the bank and implement graceful degradation for missing optional fields.​ | | `PROVIDER_UNAVAILABLE` | The bank is temporarily unavailable. Advise the user to retry later or select a different bank. Implement retry logic with exponential backoff. | | `AUTHORIZATION_FAILED` | Authorization at the bank failed. This may be due to incorrect credentials, failed SCA, or bank-side issues. Offer the user the option to retry. | ### Additional Information on Data Retrieval Failures {#additional-information-on-data-retrieval-failures} Beyond our standard status codes and API errors, we provide supplemental details to help you understand why data retrieval failed and what follow-up actions you may need to take. These insights are included in the response for consent status and data endpoints. Within the status or error object, you will find a details object that surfaces failure-specific information. This allows you to better diagnose issues and guide your users accordingly. Here is an example excerpt from a Get Consent response illustrating the structure and content you can expect: ```json { "status": "FAILED", "details": { "code": "AuthorizationFailed", "reason": "Strong Customer Authentication failed at the bank.", "provider": { "code": "SCA_FAILURE" } } } ``` Here is a list of these codes along with guidance on how to handle each one: Note: Due to the breadth of Open Finance integrations and the number of markets and providers we support, this information may not be available for every failure. The list below is not exhaustive, and we will continue to expand it over time. | **Code** | **Reason** | **Handling Recommendation** | |-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | \`\`AccountGettingFailure\` | Failure retrieving accounts | We were unable to fetch the user's accounts. The user can try again as it may be a temporary issue. Contact support if the issue persists. | | \`\`AccountNotFound\` | AIS authorization failed | We were unable to fetch the specific account. The user can try again or select a different account | | \`\`AisLoginFailed\` | Selected account was not found | Ask the user to retry and advise them to ensure they complete all Strong Customer Authentication (SCA) steps. | | \`\`AisLoginFailedAfterThreeAttempts\` | AIS login failed after three attempts | Notify the user that multiple failed login attempts have occurred. Ask the user to verify their credentials and try again later. If issues continue, they can contact their bank. | | \`\`AuthorizationFailed\` | The authorization attempt failed | The user can retry or try again using a different bank. Advise them to ensure they complete all SCA steps. | | \`\`BankServiceUnavailable\` | Bank service is unavailable | These are usually related to downtime or maintenance at the bank. The user can retry later or try with a different bank. | | \`\`ConsentExpired\` | The consent has expired | Create a new consent and guide the user through authorization again. | | \`\`ConsentRevoked\` | The consent has been revoked by the user | Respect the user's decision. Request new consent only if necessary for your service. | | \`\`DataNotAvailable\` | Requested data is not available | The bank does not provide the requested data type for this account. Check supported scopes and implement graceful handling for missing data. | | \`\`InvalidBankId\` | Bank ID is invalid | An invalid provider ID was used. If you are passing in a provider ID, verify that it is correct. Contact support if the error persists. | | \`\`InvalidPsuCredentialsBlocked\` | Customer account is blocked | When we receive this from the bank, it usually means there is a block on the user's account. Advise the user to contact their bank to resolve the issue. | | \`\`NoUsableScaMethods\` | No available authentication methods for this operation | Advise the user that their bank does not currently provide an authentication method that can be used for this type of data access. They can try with a different bank. | | \`\`ProviderDidNotReturnValidResponse\` | The bank did not return expected data. The user can try again as it may be temporary. Contact support if the issue persists. | | | \`\`RejectedByBank\` | This is a generic rejection. The user can retry or try with a different bank. If they believe it should not have been rejected, advise them to contact their bank. | | ### ISO Standards {#iso-standards} Mastercard Open Finance Data follows international standards for data formats to ensure consistency and interoperability: #### ISO Country Codes {#iso-country-codes} Country codes follow ISO 3166-1 alpha-2 standard. **Examples** | **Country** | **ISO COde** | |----------------|--------------| | United Kingdom | GB | | Germany | DE | | France | FR | | Netherlands | NL | | Spain | ES | | Italy | IT | | Poland | PL | #### ISO Currency Codes {#iso-currency-codes} Currency codes follow ISO 4217 standard. **Examples** | **Country** | **ISO COde** | |-----------------|--------------| | Euro | EUR | | British Pound | GBP | | Polish Złoty | PLN | | Swedish Krona | SEK | | Danish Krone | DKK | | Norwegian Krone | NOK | #### Date and Time Formats\| {#date-and-time-formats} Date and time values follow ISO 8601 standard: | **Format** | **Example** | **Usage** | |------------------------|---------------------------|-------------------------------------------------------| | DateTime | 2024-07-15T14:30:00Z | Full timestamp in UTC | | DateTime with Timezone | 2024-07-15T14:30:00+02:00 | Timestamp with specific timezone offset | | Date | 2024-07-15 | Dates without time (for example, consent expiry date) | All `datetime` values returned by the API are in UTC unless otherwise specified. When providing datetime values in requests, you may use either UTC (Z suffix) or include a timezone offset. Need help with error handling? Refer to the API Basics \> Error Handling documentation or contact support through the Contact Us form.