Error Handling

​

Errors

​

500 Internal Server Errors

Server errors indicate an error on Finch’s side and return an HTTP response with a 500 status code.

Common causes

• Finch is experiencing internal system issues. This is rare.
• The underlying employment system is experiencing internal system issues.
• Finch received an unsupported response from the underlying employment system and is unable to process it. These are usually quickly resolved by our support team.
• The end-user has intentionally or unintentionally revoked Finch’s access to their system. This is usually returned as a 401 - reauthenticate_user error but can sometimes be returned as 500 - server_error.

Troubleshooting steps

• Retrying immediately usually will not resolve the issue. We recommend retrying the API request in a few hours.
• If the error persists, submit a support ticket with the Finch-Request-ID present in the headers of the response.

​

401 re-authentication errors

Authentication errors indicate an error on the end user’s side. See the re-authentication docs for more on common causes and troubleshooting steps.

​

408 client connection errors

Timeout errors occur when a client connection is closed while the API server is still processing the request. Currently, our server timeout is set to 6 minutes. Therefore, our recommendation is to increase the configured client timeout to 6 minutes to ensure that the client does not timeout prematurely. If you have not configured one explicitly, there is likely a default depending on the request library you’re using. Note, it’s not common that our API takes this long to service a request.

​

Batch Requests

A number of Finch endpoints (like /individual, /employment, and /pay-statement) are batch endpoints.

For such endpoints, Finch can return errors in two ways:

1. Return an error per batch request item within the response body. The error will be in the same format described in the Error Types guide.
   • Finch also returns an error_name and error_message in the response body. These fields are now deprecated in favor of conforming to our standard error formatting, and will be removed entirely in June 2023.
2. Return an error at the HTTP status code level. The error will be in the same format described in the Error Types guide.

Response HTTP Status Code: 200

Response Body:
{
  "responses": [
    {
      // this id varies by endpoint, could also be payment_id or benefit_id
      "individual_id": "fbeabe51-e6d2-45aa-a460-4c8482528f41",
      // corresponds to the `code` parameter of the error schema in the Error Types guide
      "code": 404,
      "body": {
        "name": "not_found_error",
        "code": 404,
        "finch_code": "individual_not_found",
        "message": "The individual with id 'fbeabe51-e6d2-45aa-a460-4c8482528f41' could not be found",
        // deprecated field. corresponds to the `name` parameter of the error schema in the Error Types guide
        "error_name": "not_found_error",
        // deprecated field. corresponds to the `message` parameter of the error schema in the Error Types guide
        "error_message": "The individual with id 'fbeabe51-e6d2-45aa-a460-4c8482528f41' could not be found"
      }
    }
  ]
}

Response HTTP Status Code: 500

Error Body:
{
  "code": 500,
  "name": "server_error",
  "message": "Internal server error"
}