In this guide, you’ll learn how to identify and mitigate common errors such as server errors, reauthentication errors, and rate limit errors.
null
values and 202
responses in order to prevent errors in processing data in your application. The key behaviors your application should exhibit are are described in our
Handling API Responses guide.
manual=true
in the params to see assisted integrations in the drop down list of providers.
HTTP 500
. If this type of error occurs, implementing a few error-handling mechanisms in your application can help maintain a good user experience while still allowing you to diagnose the issue.
finch-request-id
found in the HTTP Request headers. This will help in diagnosing and rectifying the error on Finch’s side.500
errors faster.finch-request-id
present in the headers of the response for further assistance.
401 Unauthorized
and finch_code
of reauthenticate_user
(see Finch API errors). When an access token returns this, your user will need to re-authenticate by going through the Finch Connect flow again.
Since a reauthentication error means that a connection is disconnected and the access token is no longer working, your customer must be reengaged to have them reconnect their provider through Finch Connect again to get a new access token. We recommend using automatic in-app or email notifications to alert your customer that there is an issue with their connection, why reconnecting is beneficial, and the steps they need to follow to reconnect.
Finch recommends the following steps to handle reauthentication errors:
401
HTTP status code error responses with the finch_code
of reauthenticate_user
in your application while handling Finch API responses./connect/sessions/reauthenticate
endpoint. The endpoint requires that you pass in connection_id
of your customer by calling the /introspect endpoint with their access_token
.code
is generated which you will need to exchange for a new access_token
that you can use to send requests to the Finch API again. Make sure to save this new token in your database.While you will receive a new access token for the employer, everything else will remain the same. All Finch identifiers, likeindividual_id
orpayment_id
, are the same across tokens.
429 To Many Requests
when the request rate limit for an application or an individual IP address has been exceeded. Familiarize yourself with the API rate limits set before continuing.
Finch’s rate limits work on a per-endpoint basis for applications, and we refer to each distinct endpoint as a unique product. Rate limits are summed on a rolling 60-second basis for each unique product. This is commonly referred to as a Sliding or Rolling Window rate limit.
You can think of a product rate limit like a “bucket”. Therefore, when a request is made to a product (which corresponds directly to an API endpoint), a single gallon of water is added to that endpoint’s bucket, thus starting that bucket’s 60-second time-to-live (TTL) timer. After the product’s rate limit is reset after 60 seconds, the first request to that product starts the 60-second TTL again.
Ensure that you stay within these rate limits to avoid API request failures due to exceeding the limits. In case you encounter rate limit errors, implement a “back-off and retry” strategy in your application. For example, you could wait for 60 seconds (since Finch’s rate limit buckets reset after this period) and then retry the request. You could also exponentially increase the wait time between retries or use a random delay if you prefer. This will allow your application to wait for the rate limit to reset and then resume making API requests.
Below are a few ways to fix rate limit errors.
individual_ids
and send as a single request. You will receive back a single response from Finch with an array of 1000 objects containing each individual’s details.
company
, directory
, individual
, employment
, payment
, and pay-statement
endpoints.
When a request is sent to an endpoint, a single gallon of water is added to the application-level product endpoint “bucket” each time. The bucket counts all requests across all the application’s access tokens (Token A, Token B, Token C, Token D, Token E).
Organization endpoints have a capacity of 20 max requests per minute. Pay endpoints have a capacity of 12 max requests per minute.
Bucket | Capacity |
---|---|
company | 5/20 - success |
directory | 4/20 - success |
individual | 0/20 |
employment | 0/20 |
payment | 3/12 - success |
pay-statement | 0/12 |
Bucket | Capacity |
---|---|
company | 10/20 - success |
directory | 8/20 - success |
individual | 0/20 |
employment | 0/20 |
payment | 6/12 - success |
pay-statement | 0/12 |
Bucket | Capacity |
---|---|
company | 20/20 (FULL) - success |
directory | 16/20 - success |
individual | 0/20 |
employment | 0/20 |
payment | 12/12 (FULL) - success |
pay-statement | 0/12 |
company
and payment
request will both fail and return a 429 rate limit error because the application-level buckets are now full. No requests from any additional token will succeed either when calling the /company and /payment endpoints until those bucket’s 60-second Time-To-Live (TTL) timer resets. However, Token E’s request to the /directory endpoint will succeed because the application-level directory
bucket is not full (yet). Only succeeded requests count towards the application level rate limits.
Bucket | Capacity |
---|---|
company | 20/20 (FULL) - error |
directory | 16/20 - success |
individual | 0/20 |
employment | 0/20 |
payment | 12/12 (FULL) - error |
pay-statement | 0/12 |
RateLimiter
class makes requests up to the specified rate limit when initialized (ex: 20 requests per minute for the /directory endpoint) and pauses further requests until the rate limit resets after 60 seconds. The request
method of the rate limiter is used to make API requests to Finch’s endpoints, ensuring that you stay within the rate limit “bucket” quota for each endpoint. Simply initialize a new RateLimiter
class for each endpoint being called.