# Most Common Error Codes source: https://developer.mastercard.com/open-finance-au/documentation/errors/most-common/index.md This page describes error codes commonly encountered in account refresh, aggregation and Verification of Income (VOI) report flows. It is not an exhaustive list of every error that the platform or a financial institution can return. Three-digit and 9xx aggregation and refresh codes are not always returned as a distinct HTTP status. Handle these errors using the `code` field rather than the HTTP status alone. ## Frequently encountered errors {#frequently-encountered-errors} Ensure that your integration handles each of these errors. | Code | Handling area | Meaning | Retry guidance | |---------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| | `946` | Customer or consent | The financial institution accepted the token but returned no record for the request. | Do not retry automatically. | | `982` | Financial institution | The financial institution returned an unexpected error. This can occur because of an entitlement change or a temporary institution outage. | Retry later. If the error continues, ask the customer to reconnect. | | `980` | Financial institution | The platform could not connect to the financial institution. | Retry later. | | `971` | Customer or consent | The grant or authorisation code is missing or invalid, or the customer declined or cancelled consent. | Restart the consent flow. Do not retry the same request. | | `325` | Partner integration | Aggregation is already in progress for the institution login. | Retry with backoff after the current aggregation finishes. | | `970` | Platform or consent | Parameters or headers sent to the financial institution are invalid or missing. This code can also indicate an inactive institution account within an otherwise active consent. | Verify the consent and account status. Do not retry automatically. | | `973` | Partner integration | The customer is not authorised for the requested resource or data cluster. | Do not retry automatically. | | `983` | Financial institution | An unclassified HTTP error occurred in the financial institution connection. | Report the error for investigation. | | `44000` | Platform | Aggregation did not finish within the expected response window. | Check the aggregation status before submitting another request. | ## Error reference by handling area {#error-reference-by-handling-area} The handling areas below group errors by the party or state most closely associated with their resolution. Use the meaning, remediation and retry guidance for the action required. ### Customer or consent errors {#customer-or-consent-errors} These errors generally require the customer to provide consent again, re-authenticate or link an eligible account. | HTTP status | Code | Meaning and remediation | Retryable | |-----------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------| | 404 | `946` | The financial institution accepted the token but returned no record. If the condition continues for more than 24 hours, create an [SCM support case](https://developer.mastercard.com/open-finance-au/documentation/support/index.md#create-a-support-case-in-scm). The customer may need to re-authenticate. | No | | 401 | `947` | The token is invalid or has expired. Ask the customer to re-authenticate. | No | | 400, 401 or 403 | `971` | Consent was not granted or was cancelled. Restart the consent flow. | No | | 404 | `976` | The financial institution connection requires the customer to re-authenticate or provide more information. | No | | 400 | `90502` | The consent is expired, revoked or otherwise inactive. Ask the customer to provide consent again. | No | | 400 | `5030` | No eligible transaction, savings or money market account is linked for VOI. Ask the customer to link an eligible account. This condition can also return code `14020`. | No | | 404 | `38003` | The account was removed or the `accountId` is incorrect. Verify the `accountId`. | No | | 404 | `38057` | Money transfer details were not found because the account or routing details are invalid, the account is ineligible, or the institution restricted the response. Ask the customer to connect the correct account. | No | ### Financial institution errors {#financial-institution-errors} These errors originate from a financial institution connection and can be temporary. | HTTP status | Code | Meaning and remediation | Retryable | |------------------------------------------------------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------| | 502, 503 or 504 | `980` | The financial institution is unavailable. Retry later. If the condition continues for more than 24 hours, create an [SCM support case](https://developer.mastercard.com/open-finance-au/documentation/support/index.md#create-a-support-case-in-scm). | Yes | | 500 or 502 | `982` | The financial institution returned an unexpected error. Retry later. If the error continues, ask the customer to reconnect. | Conditional | | Commonly 500; other 4xx or 5xx statuses are possible | `983` | An unclassified error occurred in the financial institution connection. Report the error for investigation. | No | ### Partner integration errors {#partner-integration-errors} Resolve these errors by correcting request headers, request structure or request sequencing. | HTTP status | Code | Meaning and remediation | Retryable | |------------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------| | Varies; can appear in a successful refresh status response | `325` | A parallel refresh was submitted for the same `institutionLoginId`. Do not submit refresh requests in parallel. Wait until `aggregationSuccessDate` is greater than or equal to `aggregationAttemptDate`. | Yes, with backoff | | 401 | `10022` | The `Finicity-App-Token` is expired or invalid. Refresh the authentication token. | No | | 401 | `10026` | The `Finicity-App-Key` header is missing. Include the header. | No | | 400 | `10100` | The JSON body is unreadable, required body parameters are invalid or missing, or the consumer was not created. Validate the request against the API specification. | No | | 400 | `90005` | The `Consent-Receipt-Id` header is missing. Include this mandatory header on report generation and retrieval requests. | No | | 409 | `18001` | A report is already being generated for the customer. This applies when asynchronous mode is disabled. Wait for the existing report or enable asynchronous mode. | No | | 401 or 403 | `973` | The customer has not consented to the requested data cluster, or the financial institution has restricted access. | No | ### Platform errors {#platform-errors} | HTTP status | Code | Meaning and remediation | Retryable | |-------------|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------| | 400 | `970` | Parameters or headers sent to the financial institution are invalid or missing. Verify the consent and account status before reporting the error. | No | | 429 | `977` | The service reached a maximum limit or expired. Report the error for investigation. | No | | 500 or 502 | `990`, `991`, `994` or `997` | An internal subsystem error occurred. Create an [SCM support case](https://developer.mastercard.com/open-finance-au/documentation/support/index.md#create-a-support-case-in-scm). | No | | 400 or 500 | `10000` | An unexpected internal error occurred. Investigate the error before retrying. | Conditional | | 500 | `10300` | An encryption or decryption error occurred during report processing. Retry, then report the error if it continues. | Yes | | 202 | `44000` | Aggregation did not finish within the expected response window. This code can be returned with HTTP 202 or as an account-level status in a successful response. Check the aggregation status before submitting another request. If the condition continues, contact Mastercard Support. | Yes | | 503 | `44002` | Aggregation is temporarily unavailable. Retry after a short delay. | Yes | | 400 or 404 | `90500` | The consent receipt does not exist, or the consent service is unavailable. Retry, then report the error if it continues. | Conditional | | 404 | `14001` | The customer was removed or the `customerId` is incorrect. Verify the `customerId`. | No | ## VOI report errors {#voi-report-errors} | HTTP status | Code | Handling area | When it occurs | Retryable | |-------------|---------|---------------------------------|-------------------------------------------------------------------------------|-------------| | 401 | `10022` | Partner integration | The App-Token is expired or invalid. | No | | 401 | `10026` | Partner integration | The App-Key header is missing. | No | | 400 | `90005` | Partner integration | The mandatory `Consent-Receipt-Id` header is absent or empty. | No | | 400 or 404 | `90500` | Partner integration or platform | The consent receipt does not exist, or the consent service is unavailable. | Conditional | | 400 | `90502` | Customer or consent | The consent is expired, revoked or otherwise inactive. | No | | 404 | `14001` | Partner integration | The resource does not belong to the partner, or an invalid ID was supplied. | No | | 400 | `14020` | Customer or consent | No eligible account type is linked for VOI. | No | | 400 | `5030` | Customer or consent | No eligible transaction, savings or money market account is linked. | No | | 400 | `20400` | Partner integration | The report generation limit for a testing or sandbox partner was exceeded. | No | | 409 | `18001` | Partner integration | A report is already being generated while asynchronous mode is disabled. | No | | 400 | `10100` | Partner integration | The request contains invalid JSON or fields, or the consumer was not created. | No | | 400 or 500 | `10000` | Platform | An unexpected internal error occurred during report generation. | Conditional | | 500 | `10300` | Platform | Encryption or decryption failed. | Yes | ## Additional error-handling considerations {#additional-error-handling-considerations} **Code 970 and inactive accounts:** When one institution within an otherwise active consent is revoked, the consent receipt can remain active while the institution's account becomes inactive. In this situation, code `970` can be returned with a message indicating that parameters or headers are invalid or missing. Verify the consent and account status before changing the request. **Consent errors with HTTP 400:** Codes `90005` and `90502` return HTTP 400 even though they represent consent-related errors. Handle them using the `code` field rather than relying on the HTTP status. **Codes 946 and 947:** Code `947` means that the stored access credential is no longer accepted and the customer must re-authenticate. Code `946` means that the financial institution accepted the credential but returned no record for the requested account or resource. Handle these codes separately because they require different remediation. **Payment Enablement Bundle responses:** The Payment Enablement Bundle can return HTTP 200 with an `errors` array for one or more bundled operations. Inspect the `errors` array as well as the outer HTTP status. When an error code matches this reference, apply the corresponding remediation. **Codes 5030 and 14020:** When no eligible accounts are linked for VOI, the response can contain either code `5030` or `14020`, depending on the validation path. Handle both codes by asking the customer to link an eligible transaction, savings or money market account.