Skip to main content

​
Common Errors

Three request patterns reflect the most common errors for callers of the Entity API.
Lead’s Entity API documentation covers our API interface specification and Lead’s raw Open API. 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 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. 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.
1

Find the Role and Check its Status

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

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

​
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. By using this parameter, you are asking Lead to synchronously validate that an Entity meets the Data Requirements 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.
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 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.