Failure and Review Events

This page documents failure semantics. It intentionally shows only the fields relevant to handling failures; the complete field list for each result type lives in Webhook Payload.

How failures are represented

A failed verification normally has three layers of status:

• event describes this delivery, typically FAILED.
• flowStatus describes the overall flow after the step failed.
• data.<type>.status and its reason fields describe the individual result.

{
  "resultId": "7fd1c306-7830-4261-b372-181f742055ef",
  "event": "FAILED",
  "data": {
    "dv": {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "status": "FAILED",
      "reasons": ["DOCUMENT_EXPIRED"],
      "errorMessage": null
    }
  },
  "custom": {},
  "flowStatus": "FAILED"
}

Failure detail by result type

Result key	Failure fields
dv	reasons[], plus optional errorMessage
poa	Optional reason
form	Optional reason and errorMessage
spid	Optional reason and errorMessage
phone	Optional reason and errorMessage
wallet	Optional reason and errorMessage
kyb	Optional reason and errorMessage
geolocation	Optional reason and errorMessage

Do not build logic around human-readable error text. Prefer the structured status and reason fields when present, and retain errorMessage for diagnostics.

Failure before a result exists

A step can fail before its result record is created. In that case, identifying fields may contain empty or default values while request context and errorMessage remain available:

{
  "event": "FAILED",
  "data": {
    "dv": {
      "id": "00000000-0000-0000-0000-000000000000",
      "verificationRequestId": "d72b7afc-6841-4478-9d21-3e8dd3d26695",
      "status": "",
      "reasons": [],
      "errorMessage": "Processing failed: timeout exceeded"
    }
  },
  "flowStatus": "FAILED"
}

Treat the verification request and flow identifiers as the reliable correlation context in this case.

Review events

When human review is required, Zyphe emits REVIEW instead of FAILED:

{
  "event": "REVIEW",
  "data": {
    "dv": {
      "status": "REVIEW",
      "reasons": []
    }
  },
  "flowStatus": "REVIEW"
}

Do not mark the user as rejected when receiving REVIEW. Keep the result pending until a later webhook or API read provides the final decision. See Manual Review for the operator workflow and Statuses and codes for the full event and reason vocabulary.