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. |