In case of an error, Finch’s API will respond with an appropriate HTTP status code and error body.

Finch uses HTTP status codes to indicate the success or failure of an API request.

  • 2xx: indicates success
  • 4xx: indicates developer or user-related errors
  • 5xx: indicates Finch-related issues

Error Schema

codeintegerThe HTTP status code of the response.
namestringAn identifier, safe for programmatic use, describing the broad error category.
finch_codestringAn optional identifier describing the error in more detail. It is safe for programmatic use.
messagestringA developer friendly message explaining the error.

Error Types

NameFinch CodeCodeDescription
invalid_grant_error400The authorization code is invalid.
bad_requestinvalid_request400Failed to validate request.
bad_requestenrollment_not_found404Failed find the enrollment for an individual in a benefit.
invalid_token_error401The access_token is incorrect.
invalid_request_error401The request does not match the docs. Example: the request is missing a query parameter.
authentication_errorreauthenticate_user401The user will need to reconnect their employment system. See more here.
invalid_client_error401The provided application credentials were incorrect. Relevant to the /auth/token endpoint.
unauthorized_request_error401The access_token is missing from the header.
insufficient_scope_error403The application credentials have insufficient permissions to access the requested product.
not_found_erroritem_not_found404The requested resource could not be found.
not_found_errorbenefit_not_found404The requested benefit could not be found.
not_found_errorindividual_not_found404The requested individual could not be found.
not_found_errorpayment_not_found404The requested payment could not be found.
unprocessable_request_errorunsupported_parameters422Parameters provided are not supported by the provider or benefit. Relevant to the /employer/benefits/* endpoints.
unprocessable_request_errorinvalid_employee_enrollment422The employee is unable to be enrolled in a benefit due specific to constraints on the provider side. Relevant to the /employer/benefits/* endpoints.
rate_limit_exceeded_errorfinch_application_rl429The application has exceeded Finch’s application rate limits.
rate_limit_exceeded_errorfinch_api_ip_rl429The application has exceeded Finch’s IP Address rate limits.
rate_limit_exceeded_errorfinch_auth_ip_rl429The application has exceeded Finch Connect rate limits.
rate_limit_exceeded_errorupstream_rate_limit_exceeded429The application has exceeded upstream provider rate limits.
server_error500The server experienced an unexpected error.
not_implemented_error501Finch does not support this specific endpoint for this specific provider.
bad_gateway_errorupstream_provider_error502The server experienced an unexpected error while interacting with an upstream service, such as a provider.