Error Code Changes for US Government Verification

We are updating the error code definitions and response statuses for the US Government Verification module. These changes are designed to improve result explainability, reduce ambiguity, and make it easier to interpret session outcomes in the Omni Dashboard and via API responses.

What's Changing

1. Status Changes: `FAIL` → `UNKNOWN`for select error codes.

Several error codes that previously returned a FAIL status will now return UNKNOWN. This better reflects that these outcomes are not a definitive verification failure, rather they indicate the verification could not be completed due to missing inputs, configuration issues, or connectivity problems.

Error Code	Description	Old Status	New Status
`providerNotConfigured`	Provider is not configured or incorrectly configured for this flow	`FAIL`	`UNKNOWN`
`missingDocumentId`	Document number missing or has an invalid pattern	`FAIL`	`UNKNOWN`
`invalidExpirationDate`	Expiration date is not valid per document standards	`FAIL`	`UNKNOWN`
`notEnoughData`	One or more required fields are missing or invalid	`FAIL`	`UNKNOWN`
`missingSelfie`	Provider requires selfie for processing but not provided in session	`FAIL`	`UNKNOWN`
`connectionError`	Error occurred during processing within provider environment	`FAIL`	`UNKNOWN`
`infrastructureError`	Error occurred during processing within Incode environment	`FAIL`	`UNKNOWN`

2. Deprecated Error Codes & New Mapping

The following error codes are being deprecated. They will no longer be returned. Sessions that would have previously triggered these codes will now return one of the more specific replacement codes listed below.

Deprecated Code	Old Description	Now Mapped To
`validationError`	Grouped validation failure covering: record not found, data mismatch, restricted record, or face match failed	`userNotFound`, `faceComparisonFailed` (more specific codes per actual failure reason)
`providerUnavailable`	DMV or AAMVA provider service unavailable or credentials invalid	`connectionError`

3. Updated Error Descriptions

Some error codes retain the same status but have updated descriptions for improved clarity. No behavioral changes are associated with these, only the human-readable description has been refined. Refer to the full table of error codes for details.

Error Code Table

    <th style={{ textAlign: "left" }}>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td style={{ textAlign: "left" }}>
      `providerNotConfigured`
    </td>

    <td style={{ textAlign: "left" }}>
      **Provider Not Configured**<br />
      Provider is not configured or is incorrectly configured for this flow.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `missingDocumentId`
    </td>

    <td style={{ textAlign: "left" }}>
      **Missing Document Number**<br />
      Document number missing or has an invalid pattern.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `invalidExpirationDate`
    </td>

    <td style={{ textAlign: "left" }}>
      **Invalid Expiration Date**<br />
      Expiration date is not valid per document standards.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `notEnoughData`
    </td>

    <td style={{ textAlign: "left" }}>
      **Missing Required Data**<br />
      One or more required fields are missing or invalid.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `missingSelfie`
    </td>

    <td style={{ textAlign: "left" }}>
      **Missing Selfie**<br />
      Provider requires selfie for processing but not provided in session.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `documentTypeNotSupported`
    </td>

    <td style={{ textAlign: "left" }}>
      **Document Type Not Supported**<br />
      Invalid document type for validation by the configured provider.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `geographicRegionNotSupported`
    </td>

    <td style={{ textAlign: "left" }}>
      **Country Not Supported**<br />
      Document country not supported by the configured provider.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `geographicStateRegionNotSupported`
    </td>

    <td style={{ textAlign: "left" }}>
      **State Not Supported**<br />
      Document state not supported by the configured provider.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `connectionError`
    </td>

    <td style={{ textAlign: "left" }}>
      **Provider Connection Error**<br />
      Error occurred during processing within provider environment.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `infrastructureError`
    </td>

    <td style={{ textAlign: "left" }}>
      **Incode Processing Error**<br />
      Error occurred during processing within Incode environment.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `userNotFound`
    </td>

    <td style={{ textAlign: "left" }}>
      **User Not Found**<br />
      ID data doesn't match the government database.
    </td>
  </tr>

  <tr>
    <td style={{ textAlign: "left" }}>
      `faceComparisonFailed`
    </td>

    <td style={{ textAlign: "left" }}>
      **Face Match Failed**<br />
      Selfie does not match government database portrait.
    </td>
  </tr>
</tbody>

What's NOT Changing

The API interface is unchanged. Error codes continue to be returned in the same fields and same response structure. This update is fully backwards compatible, no integration changes are required.
Error codes remain available in Business Rules. All error codes (including newly renamed and updated ones) continue to be exposed in Business Rules, so you can configure FAIL or UNKNOWN handling as needed.
Error codes remain unchanged for non US connections. The error codes for all non US government verification connections remain unchanged.
Billing behavior is unchanged for all affected codes.

Action Required

⚠️
If your implementation uses the impacted error codes for downstream decisioning logic or alerting, please review the status changes listed above and update your logic accordingly.

If you prefer to continue failing sessions that now return UNKNOWN (e.g., connectionError), you can configure this via Business Rules without any code changes on your end.

Questions?

Reach out to your Incode integration contact or submit a support request if you have questions about how these changes may affect your specific implementation.

Updated about 2 months ago

What's Changing

1. Status Changes: FAIL → UNKNOWNfor select error codes.

2. Deprecated Error Codes & New Mapping

3. Updated Error Descriptions

What's NOT Changing

Action Required

If your implementation uses the impacted error codes for downstream decisioning logic or alerting, please review the status changes listed above and update your logic accordingly.

Questions?

1. Status Changes: `FAIL` → `UNKNOWN`for select error codes.