Failure reasons¶

A failure reason is a stored diagnostic record with a type category and an optional detail description. It may apply to the entire session or to a technology result. The presence of this record, a negative result, an HTTP request error, and the final session status are distinct indicators: consider them together.

This page describes the actual contract of the current backend. Messages that are only returned by an individual HTTP request or written to a technical log do not automatically become a failure_reason.

Where to retrieve failure reasons¶

Full and light Flow Session results use the same error format:

• POST /api/flows/sessions/result/ — full result;
• POST /api/flows/sessions/result/light/ — light result;
• <technology_block>.failure_reason — the reason for the selected technology result;
• flow_session_failure_reasons[] — reasons for the session itself and a selection of technology reasons. This is an aggregate array, not just session-level errors.

These responses have no separate root-level failure_reason for the session. In a webhook, the location of the error and field inclusion rules depend on the event.

Structure and missing values¶

The reason object contains no identifier, timestamp, technology code, or attempt number. In the aggregate array, you cannot reliably determine the source of an error from its position or text alone. The storage limit for detail is 512 characters; the code defines no common mechanism for safely truncating external messages.

Error categories¶

Values are case-sensitive. A category name describes how the backend classifies an error; by itself, it does not establish who is responsible, whether a retry is possible, or whether the rejection is final.

Errors and verification outcome¶

• result: false is possible without a reason: the initial state of some registries, an AML match when rejection on sanctions matches is enabled, or a negative DR v1 calculation without a separate record.
• result: true is possible with a reason: a confirmed example is GBDUL with allow_service_unavailable. Successfully writing values to an existing result also does not mean that a previous error is always cleared.
• result may not have a value yet. The API then excludes the field. For Liveness Core, this is also possible when the check is sent for manual review.
• KZ Info and ERD have no result field at all: analyze the data retrieval status and reason.

Session status and flow_session_result¶

During normal completion, a reason belonging to the session itself leads to FAILED. The results of active technologies are then checked: incomplete or negative verification usually produces FAILED, successful verification produces FINISHED; IN_REVIEW is provided for Liveness Core with an undetermined result. The full list of statuses is in the results overview.

The public flow_session_result is calculated separately:

1. Until the status is FINISHED or APPROVED, it returns false.
2. For selected technology results, a failure_reason or an explicit result: false produces false.
3. A missing result value is not itself checked as false; a missing single-record relation and an empty collection are handled differently.

This calculation iterates over Workflow technologies without filtering by activity, except for Person. The status check at completion uses active technologies and their results, and treats KZ Info/ERD as complete when their status is RECEIVED or FAILED. Therefore, status: "FINISHED" and flow_session_result: false can occur together, particularly when a technology error is stored. Manual APPROVED also does not bypass the check for stored errors in the public aggregate result. The session's own reasons are not checked again directly in this aggregate calculation; normal completion accounts for them through the status.

Saving a technology reason usually does not change the session status immediately. Exceptions are listed below. An intermediate negative result during PROGRESS is not equivalent to a session that has already ended with FAILED.

Workflow¶

Session-level reasons are in flow_session_failure_reasons[].

Liveness¶

Public block: liveness_result. Head Position, Short, Distance, Distance v2, Pro Max, and Core use a shared block. Its schema does not return the Liveness processing status.

Liveness calculation¶

The following reasons are generated automatically; they produce result: false and also set the processing status to FAILED.

These reasons produce result: false and the processing status FAILED. Liveness may select IN_REVIEW without a reason instead of rejecting borderline liveness or age scores; result is then absent from the public result. The check state is evaluated after waiting for the background calculations specified by the handler, not from a single intermediate frame.

Image integrity and client errors¶

Face2Face¶

Public block: face2face_result. It has no processing status.

Document Recognition¶

Public block in the API and flow.end: document_recognition_v2_result. In the separate DR2 technology.end event, the handler uses the name data.document_recognition_result; do not confuse it with the DR v1 result structure.

Errors retrieving the result:

After successful recognition, Workflow restrictions are checked sequentially. The first triggered check creates a reason and sets result: false; the recognition status remains SUCCESS. This means the document was recognized successfully but rejected by the rules.

E-Document¶

Public blocks: edocument_result and edocument_child_result. The branches below that save an error set result: false and status: "CANCELED". The session uses the general completion mechanism.

Access and document matching¶

Service errors¶

Each entry below has type: "SERVICE_ERROR"; it applies to the regular or child block if the corresponding call is part of an operation that saves errors.

Address¶

Public block: address_result.

Access confirmation response¶

Token and address requests¶

GBDFL¶

Public block: gbdfl_result. The initial record may have result: false without an error. Common token request errors are the same as for Address:

For rejected statuses, the KDP response status is saved; the session usually completes through the general mechanism.

GBDUL¶

Public block: gbdul_result.

The ability to complete the technology with ERROR_ACCEPTED does not guarantee a positive flow_session_result.

PPS¶

Public block: pps_result.

For INVALID, NOT_FOUND, and FAILED, the corresponding KDP response status is saved.

RPN¶

Public block: rpn_result. The reasons below produce result: false; call errors produce FAILED, while a rejected KDP status is saved as the technology status.

NPCK¶

Public block: npck_result.

KZ Info¶

Public block: kz_info_result, without a boolean result.

ERD¶

Public block: erd_result, without a boolean result.

AML¶

Public block: aml_result, without a separate status.

When Fail on error is disabled, these handled errors produce result: true without a new reason. When a match is found and Fail when found in sanctions lists is enabled, result: false is stored without a failure_reason. If rejection on matches is disabled, the result may be true even when matches are present. The handler does not cover every unexpected provider exception: the text of an arbitrary failure cannot be treated as a new public reason.

MRZ¶

Public block: mrz_result.

MxDocument¶

Public block: mxdocument_result, without a processing status. All listed automatic reasons have SERVICE_ERROR and produce result: false.

Tunduk¶

Public block: tunduk_result, without a processing status. A passport request error stores result: false.

IP checks¶

Public array: ip_check_results[]. All supplied addresses are checked; reasons for one item do not replace checking the other items. Use the boolean result rather than trying to infer the outcome from a single verdict.

Data retrieval¶

Checking the retrieved indicators¶

Checks run in table order; the first triggered check is selected. The reason produces result: false, usually with verdict: "blocked" when data is available.

If this function is called, it changes only previously positive IP results: it sets false and a reason but does not change verdict. A record with verdict: "ok" and a country error is therefore possible by design, but an active path that creates it through this function has not been confirmed.

Questionnaires¶

Public array: questionnaire_results[].

One-time code (OTP)¶

Public array: otp_results[].

DS Identifier / DS NPCK / DS Signer¶

Public blocks: ds_identifier_result and ds_signer_result. DSI and DSN use a shared identification block. These blocks do not return Digital Signature processing statuses.

DSI / DSN identification¶

In branches that save the error, result: false and processing status FAILED are set.

DSS signing¶

Stored certificate initialization, reissuance, and signing errors produce result: false and processing status FAILED.

During certificate reissuance, known provider messages are translated before being saved. For 4xx responses, the category is CLIENT:

This mapping does not guarantee that the provider returns every message specifically during reissuance. It defines the conversion if such a message is received in this operation; other messages are saved as received.

During certificate acceptance, the same translation is applied, but no new failure reason is saved. During signing, a message containing неверный пароль, matched case-insensitively, becomes the HTTP error Digital Signature incorrect certificate password without a new reason and without changing the record to FAILED; this allows the password to be corrected and the call retried while the other conditions remain satisfied. Invalid verification code from the old page has not been confirmed as a fixed reason in the current code.