Error Codes and Aggregation Status Codes

The following is a list of API error codes and aggregation status codes that can be returned from the API. The difference between API error codes and aggregation status codes is what layer the error occurs. API error codes are going to be errors that need to be addressed from a development level and are errors regarding the format or body of data in the API calls. Aggregation status codes are in relation to the result of what happened when Finicity attempted to connect to the financial institution.

API error codes could have various HTTP responses and the error code will typically show up in the body of the response (more details below for each case). Aggregation status codes will come back consistently as HTTP 500 response and in the body of the response you will get the specific aggregation status code

Codes that are aggregation status codes (marked "AGG" below) will appear in the field aggregationStatusCode of a customer account record for accounts added in the system. An aggregation status code of "0" means the account is aggregating successfully.

Common API Error Codes

This list is not meant to be comprehensive of all error codes but should be the most common cases. We may add more over time as needed. Most error codes you run into on an API level should have details in the body of the response as to why the error is occurring. If there is an undefined error code feel free to reach out to support@finicity.com.

Code Description HTTP Response Required Action
10005 Missing Parameter HTTP 400 A required field was left blank, or contained only whitespace. Submit the request again, with valid text in all required fields.
331 Expired MFA session HTTP 408 See MFA Session Identifier to understand MFA sessions.
10023 Expired (Finicity-App-Token) HTTP 401 See Partner Authentication to understand Finicity-App-Token.
10106 Invalid Account Type HTTP 400 See Account Types to understand supported account types.
10814 Invalid MFA session identifier HTTP 500 See MFA Session Identifier to understand MFA sessions.
45002 Invalid character HTTP 500 The characters PIPE "|" and TILDE "~" and LESS_THAN "<" are not supported in account passwords and some other data fields. Prompt the user to login to their account directly at the institution's website and change their password to remove the unsupported character. Then retry the failed operation, with the new password.
110039 Username is not as per the policy. HTTP 500 See Customers for the username constraints.

325

5006

The account is currently being aggregated. HTTP 500 This is only an informational message. The app has called one of the Refresh services multiple times. Because the first operation is still in process, the second call is ignored. Call Get Customer Account periodically to see the account status. The refresh operation is complete when aggregationStatusCode is 0 and aggregationSuccessDate is greater than or equal to aggregationAttemptDate.

User Action Aggregation Status Codes

Some status codes that occur during aggregation are related to action the end user must take in order for it to work properly. A list of these statuses and their explanations appears below.

Code

Description

Type

Required Action

103

Invalid Credentials

HTTP 500; AGG

  1. Call Get Customer Account Login Form to get the login form for this account.
  2. Prompt the customer for the correct credentials.
  3. Call Modify Customer Account Credentials to store the new credentials.

108

User Action Required

HTTP 500; AGG

Prompt the user to login to their account directly at the institution's website and follow the instructions there. (This typically means that there is an unexpected notice for the customer at the website. A common example would be customer has to accept new terms or has been invited to participate in a program like e-statements)

109

User Action Required

HTTP 500; AGG

Prompt the user to login to their account directly at the institution's website and follow the instructions there. (This typically means that the customer institution is requiring that they change their security information like password or security questions)

185

Missing or Incorrect MFA Answer

HTTP 500; AGG

During the nightly batch aggregation or during a non-interactive refresh MFA was needed. Call Refresh Customer Account and follow the MFA sequence to prompt the user for the missing information.

187

Missing or Incorrect MFA Answer

HTTP 500; AGG

Customer has answered their MFA question incorrectly. Call Refresh Customer Account and follow the MFA sequence to prompt the user to answer MFA again with the correct answer.

931

Bank security requires a one time passcode for every connection.

HTTP 500; AGG

The bank requires a one time passcode every time the customer wants their financial information. Inform the customer of this situation and facilitate them refreshing every time they use the app to enter the one time passcode so they can get the latest financial info.

936

Customer's language preference is not supported for aggregation.

HTTP 500; AGG

The customer has a language preference other than English. This could potentially cause issues with the integration for this specific institution. Have the customer change their language preferences to English for their accounts in order to get the best experience.

Institution Outage or Maintenance Aggregation Status Codes

To keep you as a partner and by pass through your end user better informed we have some specific statuses that we use to better communicate problems with a particular connection and what actions you should take. We may add more statuses to this list over time as we find scenarios that specific codes could provide helpful data.

Code

Description

Type

Required Action

102

320

580

Retry Error or Problem Connecting to the Institution

HTTP 500; AGG

Wait a few minutes and try the operation again. If the problem persists, escalate the issue through the API.

900

903

904

Connection currently under maintenance.

HTTP 500; AGG

Gathering additional authentication information in order to proceed with fix. Customer should check back every several days and attempt to refresh or add accounts again. Each attempt will store information needed by engineering to continue to fix the connection. One attempt every 3 to 5 days should be sufficient.

901

Institution connection currently under maintenance.

HTTP 500; AGG

Gathering additional authentication information in order to proceed with fix. Similar action to (900 / 903 / 904 / 915), but user should attempt to log-in up to 5 attempts in a row if possible in order to store all the additional authentication information needed since this is related to an MFA type where security question information needs to be stored.

910

Institution connection is currently down and is being worked on.

HTTP 500; AGG

Inform the customer that we are aware that the connection is down and we are working on fixing it. Have them check back every 3 to 5 days.

915

Institution not working for a specific user or group of users.

HTTP 500; AGG

Gathering additional authentication information in order to proceed with fix. Customer should check back every several days and attempt to refresh or add accounts again. Each attempt will store information needed by engineering to continue to fix the connection. One attempt every 3 to 5 days should be sufficient.

916

Institution not working for a specific user or group of users.

HTTP 500; AGG

Gathering additional authentication information in order to proceed with fix. Customer should check back every several days and attempt to refresh or add accounts again. Each attempt will store information needed by engineering to continue to fix the connection. Customer should attempt every every 3 to 5 days and make up to 5 attempts in a row if possible in order to store all the additional authentication information needed.

920

to

929

This institution does not currently support aggregation.

HTTP 500; AGG

There could be multiple reasons that an institution does not support aggregation. We recommend the customer reach out to their financial institution and tell them to contact Finicity by emailing ryan.christiansen@finicity.com in order to resolve the issue and become a supported institution.

Other HTTP Codes

See this REST API Tutorial page for an explanation of other HTTP codes, such as HTTP 204, 400, or 429.

All Other Aggregation Status Codes

All other aggregation problems are automatically added to our support system’s list of known issues. Our engineers are working around the clock to fix these known issues as quickly as they can. 

Escalating an Issue
In cases where a live customer is actually waiting for an issue to be resolved, you can escalate the issue by calling the service Escalate Aggregation Error, or by sending an email to support@finicity.com. This opens a high-priority ticket which can be tracked by clicking Help > View Support Tickets inside the Developer Portal. You can also use the Escalate Aggregation Error or send sending an email to support@finicity.com

Escalation is reserved for cases where a live customer is actually waiting for an issue to be resolved! We strive to fix all known issues within a reasonable amount of time, including those issues that have not been escalated through this service. If you flood the system by escalating issues that customers are not waiting for, you will in fact degrade the experience for your customers who are actually waiting for an issue to be resolved.

Have more questions? Submit a request

Comments

  • Avatar
    Steven Lu

    Hey guys, for Invalid MFA session identifier, 10184: I believe this number is incorrect. We've been using 10814 instead for the exact error.

  • Avatar
    Chip Whitmer

    You're right! Thanks for catching this typo. I have updated the document.

Powered by Zendesk