> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting verification

> Track linkage separately from the verdict, and resolve every verification error code.

Verification spans your API call, Venly, an external platform, and a human reviewer. When something
stalls, the first job is working out *where*. That's what the linkage endpoint is for.

## Linkage is not the verdict

Two different questions, two different endpoints. Mixing them up is the most common mistake here.

| Question | Where to look |
| - | - |
| **"Is this party verified?"** | `kycStatus` / `kybStatus` on [Get a party](/api-reference/Finance-API/parties/get-party-details) |
| **"What's happening with the verification plumbing?"** | [Get verification linkage](/api-reference/Finance-API/parties/get-verification-linkage) |
| **"Is it waiting on my end customer, and for what?"** | [Get a party's KYC status](/api-reference/Finance-API/parties/get-a-partys-kyc-status) |

[`GET /parties/{partyId}/iv-verification`](/api-reference/Finance-API/parties/get-verification-linkage)
reports how far the party got through the pipeline:

| `status` | Meaning |
| - | - |
| `NOT_LINKED` | No verification has been started for this party. |
| `SUBMITTED` | A verification request was submitted. |
| `FORWARDED` | Forwarded for verification. |
| `ACCEPTED` | The platform accepted the case. |
| `COMPLETED` | A verdict was received and applied. |
| `FAILED` | The linkage failed, or the verdict was a decline. |

<Warning>
  `COMPLETED` does **not** mean approved. It means a verdict landed. Read the party's own
  `kycStatus`/`kybStatus` for the outcome — a declined verification also reaches `COMPLETED` or `FAILED`
  depending on where it ended.
</Warning>

This endpoint always returns `200` for an existing party. It never errors to signal a verification
outcome, and it reflects **party-level** linkage only — never your company's tenant provisioning state.

### `ivCaseReference` is durable

Once the platform returns a case reference, it is populated and **never cleared** — including on
`FAILED` after a decline. It's `null` only while no reference was ever returned.

Read the field directly rather than gating on `status`:

```js theme={null}
// Good — the reference is there whenever it exists
const { ivCaseReference } = linkage;
if (ivCaseReference) attachToSupportTicket(ivCaseReference);

// Fragile — misses FAILED cases that do have a reference
if (linkage.status === 'COMPLETED') { /* ... */ }
```

That durability is the point: **quote `ivCaseReference` to Venly support** when investigating a stuck
or disputed verification. It survives declines specifically so a rejected case can still be traced.

## Diagnosing a stall

| Symptom | Likely cause | Next step |
| - | - | - |
| `status: NOT_LINKED` long after you minted a link | The user never opened the URL | Re-send it — [minting is idempotent](/guides/finance/onboarding/hosted-verification#links-do-not-expire) |
| Stuck at `SUBMITTED` or `FORWARDED` | In flight on the platform side | Wait; if it persists, quote `ivCaseReference` to support |
| `ACCEPTED` for a long time | Awaiting human review — normal for KYB, **or** waiting on the end customer | Read the [KYC status](/api-reference/Finance-API/parties/get-a-partys-kyc-status). `IN_REVIEW`: wait, and [use a webhook](/guides/finance/webhooks) instead of polling. `AWAITING_CUSTOMER`: [issue a completion link](/api-reference/Finance-API/parties/issue-a-kyc-completion-link) |
| `COMPLETED` but account still blocked | Verdict was a decline, **or** the wallet gate isn't clear | Read the party's status; then check [wallet readiness](/guides/finance/kyc-verification#wallet-readiness-aml-and-permits-for-self-custody) |
| `FAILED` with a `null` reference | Never reached the platform | Retry; if it repeats, it's configuration — contact Venly |
| Party `VERIFIED` but transfers still rejected | You're reading the party, not the account | Read the **account's** `kycStatus` |

<Note>
  That last row catches people regularly. The party and the account each carry their own status, and only
  the **account's** `kycStatus` gates money movement. See
  [Roles & entities](/guides/finance/onboarding/roles-and-entities#account).
</Note>

## Every verification error code

### Provisioning and eligibility

These are configuration, not transient. Retrying will not help.

| Status | Code | Meaning |
| - | - | - |
| `409` / `400` | `verification-not-provisioned` | Your company has no provisioned verification tenant. Contact Venly. |
| `409` | `party-already-verified` | The party is already `VERIFIED`. Nothing to do. |
| `404` | `kyc-status-not-found` | The party has no verification on record, so there's no status to read or complete. Start one first. |
| `409` | `kyc-not-completable` | A completion link was requested for a verification that is already decided, isn't waiting on the customer, or wasn't started from a Sumsub token. Read the [KYC status](/api-reference/Finance-API/parties/get-a-partys-kyc-status). |
| `400` | `verification-kyc-only` | `party.sumsubToken` supplied but `partyType` is not `INDIVIDUAL`. |
| `400` | `verification-self-custody-only` | `party.sumsubToken` supplied but your wallet type is not `SELF_CUSTODY`. |
| `400` | `sumsub-token-not-supported` | `sumsubToken` sent to `POST /parties`. It only works on `POST /accounts`. |
| `400` | `kyc-status-not-settable` | `kycStatus` `VERIFIED` or `REJECTED` supplied at account creation. `NOT_REQUIRED` is the only settable value. |
| `400` | `kyc-not-required-not-allowed` | `kycStatus: NOT_REQUIRED` supplied but no Venly admin has enabled the tenant-managed KYC flag on your company tenant. You can't retry past this — either ask Venly to enable it, or verify via a [hosted link](/guides/finance/onboarding/hosted-verification) or [Sumsub token sharing](/guides/finance/onboarding/sumsub-token-sharing). |

### Tokens

| Status | Code | Retryable | Meaning |
| - | - | - | - |
| `400` | `SUMSUB_TOKEN_NOT_REDEEMABLE` | **Yes, with a fresh token** | Expired or already used. The whole account-creation transaction rolled back. |

See [mint the token late](/guides/finance/onboarding/sumsub-token-sharing#mint-the-token-late) — this is
almost always a token-age problem.

### Platform

| Status | Code | Retryable | Meaning |
| - | - | - | - |
| `500` | `identity-verification-rejected` | No | The platform rejected the request itself. Contact support. |
| `503` | `identity-verification-unavailable` | **Yes** | Platform unreachable. Retry with exponential backoff. |

The distinction matters: `500` means *your request was understood and refused*, `503` means *nobody
answered*. Only retry the second.

### Downstream provisioning

Bank-rail provisioning onboards the account holder for verification, so it surfaces
verification state through its own codes:

| Status | Code | Retryable | Meaning |
| - | - | - | - |
| `409` | `partner-onboarding-pending` | **Yes** | The account holder's verification is still pending. Retry once approved. |
| `422` | `partner-onboarding-rejected` | No | Verification was rejected or revoked. Provisioning cannot proceed. |
| `400` | `account-holder-unresolved` | No | The account doesn't resolve to exactly one active account-holder party. |
| `400` | `party-required` / `party-name-required` | No | No linked account-holder party, or that party has no legal name. |

`partner-onboarding-pending` vs `partner-onboarding-rejected` is the retryable/terminal split
for [virtual bank accounts](/guides/finance/virtual-bank-accounts#verification-gates) — the two look
similar but only the first is worth a retry.

### Pay-out recipient gate

Not verification errors as such, but they're what a cleared KYC/KYB still runs into:

| Status | Code | Meaning |
| - | - | - |
| `422` | `recipient-not-authorized` | No `PAYOUT_RECIPIENT` role on this account, **or** the party's KYC/KYB isn't cleared. |
| `422` | `recipient-role-inactive` | The role exists but is `INACTIVE`. |

A verified party is not automatically a permitted pay-out recipient — see
[the recipient gate](/guides/finance/onboarding/roles-and-entities#the-recipient-gate).

## Retry policy at a glance

| Do retry | Don't retry |
| - | - |
| `503 identity-verification-unavailable` | `500 identity-verification-rejected` |
| `409 partner-onboarding-pending` (once approved) | `422 partner-onboarding-rejected` |
| `400 SUMSUB_TOKEN_NOT_REDEEMABLE` (with a **fresh** token) | Anything `*-not-provisioned` or `*-only` |

## Next steps

<CardGroup cols={2}>
  <Card title="Onboarding lifecycle" icon="route" href="/guides/finance/onboarding/lifecycle">
    The three gates and how they compose.
  </Card>

  <Card title="Errors & error codes" icon="triangle-exclamation" href="/guides/finance/errors">
    The API-wide error reference.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.