Troubleshooting verification

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
”What’s happening with the verification plumbing?”	Get verification linkage

GET /parties/{partyId}/iv-verification 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:

// 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
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 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
`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.

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 or 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 — 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 — 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.

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`

Overview

Recipes

Onboarding & Verification

Core Concepts

Parties

Accounts

Virtual Bank Accounts

Supported Assets

Wallets

Transfers

Fiat to Crypto Payment Sessions

Payout Bank Accounts

Payout Routes

Payouts

Permits

Allowances

Webhooks

Reference

Troubleshooting verification

Linkage is not the verdict

`ivCaseReference` is durable

Diagnosing a stall

Every verification error code

Provisioning and eligibility

Tokens

Platform

Downstream provisioning

Pay-out recipient gate

Retry policy at a glance

Next steps

Onboarding lifecycle

Errors & error codes

​Linkage is not the verdict

​ivCaseReference is durable

​Diagnosing a stall

​Every verification error code

​Provisioning and eligibility

​Tokens

​Platform

​Downstream provisioning

​Pay-out recipient gate

​Retry policy at a glance

​Next steps

Onboarding lifecycle

Errors & error codes

Linkage is not the verdict

`ivCaseReference` is durable

Diagnosing a stall

Every verification error code

Provisioning and eligibility

Tokens

Platform

Downstream provisioning

Pay-out recipient gate

Retry policy at a glance

Next steps