Handling Timeouts

The services Add All Accounts, Activate Customer AccountsRefresh Customer Accounts, and Load Historic Transactions for Account will retrieve account data for the specified account(s) from the institution. This usually returns quickly, but in some scenarios (depending on the institution) the call may take a few minutes to complete. This can result in a timeout condition. The Finicity engine will return HTTP 202 (Accepted) in this case, but other connecting points along the route may trigger a different status code such as HTTP 408 (Request Timeout), HTTP 504 (Gateway Timeout), or some other status code. Some HTTP clients will show no HTTP code at all, but only a notice that the connection is closed with 0 bytes received.

In all of these situations, the aggregation process will continue executing on our server until all operations have been completed for the request. This could take several minutes, depending on the institution.

Timeouts are part of the design of this platform. Because the time required to connect to an institution is dependent on many factors (the bank's platform, the number of accounts accessed by the given credentials, the amount of activity on the individual accounts, etc), a portion of your calls to these services will return a timeout, which should be handled as described below. Timeouts are only a concern if they are occurring on more than about 10% of these calls.

Recommended Timeout Settings

Adjusting the timeout setting on requests sent to the Finicity API can reduce the number of timeout incidents, but probably will not eliminate them completely.

Most services will function fine with a request timeout setting of 20 seconds. For those services that connect to the institution (with or without MFA Answers), a longer timeout setting is recommended.

180 seconds

120 seconds

Feel free to experiment with different values to find the optimal setting for your application.

Recovering from a Timeout

Activate Customer Accounts

In case of a timeout in any of these services (with or without MFA Answers), your code should enter a loop. The loop should wait for 20 seconds and then call the service Get Customer Account once to check the account status.

While the aggregation is in-process, the <account> record returned will not include fields <aggregationStatusCode> or <aggregationSuccessDate>. The loop should repeat every 20 seconds until aggregation is complete.

When aggregation is complete, you will see the field <aggregationStatusCode> with a value of 0, and <aggregationSuccessDate> containing a time stamp.

At this point, you can call Get Customer Account Transactions to view transactions for the account.

An aggregation status code of 185 means that the process encountered an MFA challenge after the timeout occurred. In this case, call Refresh Customer Account to resolve the MFA challenge and complete the activation process.

Any other aggregation status code (any value except 0 or 185) means that the activation has failed (see Handling Aggregation Status Codes).

Refresh Customer Account

In case of a timeout in any of these services (with or without MFA Answers), your code should enter a loop. The loop should wait for 20 seconds and then call the service Get Customer Account once to check the account status.

When the aggregation is complete, the value <aggregationAttemptDate> in the <account> record will be updated to show that this aggregation attempt is complete. The loop should repeat every 20 seconds until this date is updated to a time greater than the initial call to refresh the account.

At this point, you can call Get Customer Account Transactions to view transactions for the account.

An aggregation status code of 185 means that the process encountered an MFA challenge after the timeout occurred. In this case, call Refresh Customer Account to resolve the MFA challenge and complete the activation process.

Any other aggregation status code (any value except 0 or 185) means that the activation has failed (see Handling Aggregation Status Codes).

Load Historic Transactions

When Finicity returns HTTP 202 (Accepted) from these services (with or without MFA Answers) the response will include an XML document with the account number and status:

<account>
<id>ACCOUNT_ID</id>
<aggregationStatusCode>325</aggregationStatusCode>
<status>IN_PROGRESS</status>
</account>

In this case your code should enter a loop. The loop should wait for 20 seconds and then call the service Load Historic Transactions once to check the status of the operation.

While the operation is in-process, you will receive another status HTTP 202 (Accepted) with the same body as before. The loop should repeat every 20 seconds until the operation is complete.

When the operation is complete, you will receive the status HTTP 204 (No Content). This means that historic transactions have been loaded successfully, and the transactions are now available by calling Get Customer Account Transactions.

 

Have more questions? Submit a request

Comments

Powered by Zendesk