> ## 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) |
[`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. |
`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.
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 | Wait. [Use a webhook](/guides/finance/webhooks) instead of polling |
| `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` |
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).
## 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. |
| `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` | `recipient-verification-pending` | **Yes** | The account holder's verification is still pending. Retry once approved. |
| `422` | `recipient-verification-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. |
`recipient-verification-pending` vs `recipient-verification-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 recipient-verification-pending` (once approved) | `422 recipient-verification-rejected` |
| `400 SUMSUB_TOKEN_NOT_REDEEMABLE` (with a **fresh** token) | Anything `*-not-provisioned` or `*-only` |
## Next steps
The three gates and how they compose.
The API-wide error reference.