> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> The most common errors when calling the Entity API.
## Common Errors
Three request patterns reflect the most common errors for callers of the Entity API.
Lead's [Entity API documentation](/api-reference/endpoint/entity/create-an-entity) covers our API interface specification and Lead's [raw Open API](https://docs.lead.bank/openapi.json). Any request that violates this specification will return a `422` — for example failing to include a required field in a `POST` entity request.
Lead runs a [synchronous set of business validations](/api-integrations/entity/overview) over Entity `POST` / `PATCH` requests. If the request violates any of those checks, the API will return a 422.
You may specify an `intended_role` in a `POST` / `PATCH` request. This triggers a synchronous evaluation of whether the data points being provided satisfy the data requirements for the specified role.
Failed role evaluations when the `intended_roles` parameter is part of the request will return a 422 that specifies the role check that failed. Of course, removing the `intended_role` will eliminate the error, but then the error will be surfaced when the `entity_id` is passed in a downstream use-case.
Synchronous errors surfaced through the use of the `intended_role` parameter are identical to checks evaluated in the `role_details` of the `GET` entity response.
## **Troubleshooting Role Eligibility**
While Role Eligibility checks only surface `422` responses if the `intended_roles` parameter is used in the `POST` or `PATCH` entity request, they do surface information to callers about additional data requirements that must be met in order to fulfill a particular entity [use case](/api-integrations/entity/overview).
To determine why an entity is not eligible for a role, you'll inspect the `role_details` array within the `entity` object. This process will tell you exactly which checks are failing and for which entity.
See the following steps for determining how to interpret role eligibility failures and handle them to unlock entity use cases as needed.
In the `role_details` array, find the object where the `name` matches the role you're checking (e.g., `account_holder`, `authorized_signer`, or `authorized_user`).
Once you've found the correct role object, check its `status` field:
* `active`: The entity has passed all checks and is eligible for this role.
* `inactive`: The entity is not eligible. Proceed to the next step to diagnose the failure.
If the status is `inactive`, look inside that role's `criteria_details` array. This array explains what went wrong.
Each object in `criteria_details` contains:
* `entity_id`: The ID of the entity that has the problem and **must be updated**.
* `failed_checks`: A list of one or more error codes.
Refer to the Role Check Failure table below to understand what each code in the `failed_checks` list means and how to resolve it.
## **Understand Indirect Failures (Child Entities)**
Sometimes, an entity's role is `inactive` because a **related child entity** (like a control person or beneficial owner) has failed its own required checks. The `criteria_details` array is designed to point you directly to that failing child entity.
**Example**
Let's say a `business` is `inactive` for the `account_holder` role.
1. **The Requirement:** For a `business` to be an `account_holder`, it must have a `control_person`. That `control_person` entity must, in turn, be eligible for the `authorized_signer` role.
2. **The Dependency:** To be an `authorized_signer`, the `control_person` entity must have a `passed` KYC status.
3. **The Failure:** In this case, the `control_person` entity failed their KYC check.
4. **The Result:** Because the `control_person` is not a valid `authorized_signer`, the parent `business` cannot become an `account_holder`. The `criteria_details` for the `business` will contain an object pointing to the `control_person`'s `entity_id` with a `failed_checks` list containing `CheckKYCStatus`.
This tells you that you must update the `control_person` entity to resolve the issue for the `business` entity.
`business` and `sole_prop` entities will always have an `inactive` status for the `authorized_signer` and `authorized_user` roles.
This is expected behavior and does not indicate an error.
## Role Check Failure Codes
| **Code** | **Description** | **Entity Type** | **Possible Roles** | **How to Resolve** |
| -------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CheckFirstName` | Requires first name that is at least 1 alphanumeric character | individual | Account Holder, Authorized Signer, Authorized User | Update entity to include `individual_details.first_name`. |
| `CheckLastName` | Requires last name that is at least 2 alphanumeric characters | individual | Account Holder, Authorized Signer, Authorized User | Update entity to include `individual_details.last_name`. |
| `CheckPhoneOrEmail` | Requires valid phone number or email address | individual, business, sole\_prop | Account Holder, Authorized Signer, Authorized User | For entities of type `individual`, update `individual_details.contact_methods` to include at least one email or phone number. For `business` or `sole_prop`, update `business_details.contact_methods`. |
| `CheckPhysicalAddress` | Requires physical address | individual, business, sole\_prop | Account Holder, Authorized Signer | For `individual`, update `individual_details.addresses.physical_address`. For `business` or `sole_prop`, update `business_details.addresses.physical_address`. A physical address must include `line_1`, `city`, and `country`. If `country` is `US`, `state` and a valid 5 or 9 digit `postal_code` are also required. |
| `CheckDateOfBirth` | Must be 18 years or older | individual | Account Holder, Authorized Signer | Update `individual_details.date_of_birth` with the correctly formatted (YYYY-MM-DD) date, indicating the entity is over 18. |
| `CheckGovernmentID` | For US entity, requires US tax ID. For non-US, requires other government ID. | individual, business, sole\_prop | Account Holder, Authorized Signer | For a US `individual`, populate `individual_details.identification_details` with a valid `ssn` or `itin`. For a US `business` or `sole_prop`, populate `business_details.identification_details` with a valid `ein`, `ssn`, or `itin`. For a non-US entity, provide documents under `identification_documents`. |
| `CheckOFAC` | OFAC must have passed and `ofac_screened_at` must be present | individual, business, sole\_prop | Account Holder, Authorized Signer | `ofac_details.result` must be `passed` and `ofac_details.screened_at` must be a valid past timestamp. |
| `CheckKYCStatus` | KYC must have passed and `kyc_screened_at` must be present | individual, business, sole\_prop | Account Holder, Authorized Signer | `kyc_details.result` must be `passed` and `kyc_details.screened_at` must be a valid past timestamp. |
| `CheckRiskScore` | Requires risk score | individual, business, sole\_prop | Account Holder | `risk_score` must be populated with a value of `low`, `medium`, or `high`. |
| `CheckBusinessName` | Requires business name that is at least 2 alphanumeric characters | business, sole\_prop | Account Holder | `business_details.business_name` must be populated with a value of at least 2 alphanumeric characters. |
| `CheckBusinessType` | Requires business type | business, sole\_prop | Account Holder | `business_details.type` must be populated. |
| `CheckBusinessIndustry` | Requires NAICS code(s) for business industry | business, sole\_prop | Account Holder | `business_details.industry` must be populated with a valid 2-6 digit 2022 NAICS code. A reference file is available at the [Census Bureau](https://www.census.gov/naics/). |
| `CheckChildEntityNotFound` | Business/sole prop must have a corresponding individual entity for owners/control persons. | business, sole\_prop | Account Holder | The `entity_id` in `beneficial_owners`, `control_persons`, or `sole_proprietor` must reference a valid `individual` entity who meets `authorized_signer` data requirements. |
| `CheckManualReviewStatus` | Manual review is pending for at least one validation check | individual, business, sole\_prop | Account Holder, Authorized Signer, Authorized User | Contact your Lead Technical Account Manager. |
| `CheckControlPersonExists` | Requires at least one control person for business entities | business | Account Holder | For `business` entities, the `control_persons` list must include at least one valid item referencing an `individual` entity who meets `authorized_signer` data requirements. A `title` is also required. |
## Intended Role Parameter
**Notes for using the intended roles parameter in POST and PATCH requests or Customer File Uploads**
`intended_roles` is an optional parameter that may be used when sending an Entity Record to Lead. It should be used when, as a *caller*, you believe you have captured all necessary data points to satisfy a [Role Use Case](/api-integrations/entity/roles). By using this parameter, you are asking Lead to **synchronously** validate that an Entity meets the [Data Requirements](/api-integrations/entity/roles) for the intended use-case.
This prevents downstream failures. For instance, if an Entity is created *without* sufficient data requirements for the Account Holder role is created
If `intended_roles`: \[`account_holder`] is part of the request, the Entity upload will fail (and via API, you will return a 4xx response)
If `intended_roles` is *not* part of the request, and the Entity creation meets all minimal schema requirements, but not the data requirements necessary for a particular role, Lead will successfully ingest the entity record. The `role_details` parameter of the entity response will confirm which roles the entity meets necessary data requirements for.
`intended_roles` is a purely optional synchronous validation.
If the Account Holder (or other roles) data requirements are met, and you do not pass the `intended_roles` parameter, Lead will still successfully consider the entity eligible for the Account Holder (or other roles) role in downstream use cases such as [Account Number creation](/api-integrations/account-number/overview).
An alternative to providing the `intended_roles` parameter is to check the `role_details` parameter in the entity response as a source of truth for Account Holder eligibility.
## Error Handling and Retry
1. You will get a [success message in Slack](/file-integrations/file-delivery/slack-alerts) if the batch of files work with the list of files
2. Upon invalid file upload you will see the error messages in your Slack alert channel
3. You can fix the batch by updating the version of the file that needed to be fixed and upload it again. Lead will kick off validation for the latest version of each file in the batch.