Errors
Error Types
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 success4xx: indicates developer or user-related errors5xx: indicates Finch-related issues
Error Schema
| Name | Type | Description |
|---|---|---|
code | integer | The HTTP status code of the response. |
name | string | An identifier, safe for programmatic use, describing the broad error category. |
finch_code | string | An optional identifier describing the error in more detail. It is safe for programmatic use. |
message | string | A developer friendly message explaining the error. |
Error Types
| Name | Finch Code | Code | Description |
|---|---|---|---|
invalid_grant_error | 400 | The authorization code is invalid. | |
bad_request | invalid_request | 400 | Failed to validate request. |
bad_request | enrollment_not_found | 404 | Failed find the enrollment for an individual in a benefit. |
invalid_token_error | 401 | The access_token is incorrect. | |
invalid_request_error | 401 | The request does not match the docs. Example: the request is missing a query parameter. | |
authentication_error | reauthenticate_user | 401 | The user will need to reconnect their employment system. See more here. |
authentication_error | account_setup_required | 401 | The user will need to connect their employment system. |
invalid_client_error | 401 | The provided application credentials were incorrect. Relevant to the /auth/token endpoint. | |
unauthorized_request_error | 401 | The access_token is missing from the header. | |
payment_required | payment_required | 402 | The application has unpaid invoices and cannot access the Finch API until payment is settled. |
error_permissions | insufficient_account_permissions | 403 | The user will need to update the permissions assigned to the third-party admin account. |
insufficient_scope_error | 403 | The application credentials have insufficient permissions to access the requested product. | |
not_found_error | item_not_found | 404 | The requested resource could not be found. |
not_found_error | benefit_not_found | 404 | The requested benefit could not be found. |
not_found_error | individual_not_found | 404 | The requested individual could not be found. |
not_found_error | payment_not_found | 404 | The requested payment could not be found. |
client_connection_closed | 408 | The client connection is closed while the API server is still processing the request. Currently, our server timeout is set to 6 minutes. | |
unprocessable_request_error | unsupported_parameters | 422 | Parameters provided are not supported by the provider or benefit. Relevant to the /employer/benefits/* endpoints. |
unprocessable_request_error | invalid_employee_enrollment | 422 | The 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_error | finch_application_rl | 429 | The application has exceeded Finch’s application rate limits. |
rate_limit_exceeded_error | finch_api_ip_rl | 429 | The application has exceeded Finch’s IP Address rate limits. |
rate_limit_exceeded_error | finch_auth_ip_rl | 429 | The application has exceeded Finch Connect rate limits. |
rate_limit_exceeded_error | upstream_rate_limit_exceeded | 429 | The application has exceeded upstream provider rate limits. |
server_error | 500 | The server experienced an unexpected error. | |
not_implemented_error | 501 | Finch does not support this specific endpoint for this specific provider. | |
bad_gateway_error | upstream_provider_error | 502 | The server experienced an unexpected error while interacting with an upstream service, such as a provider. |