Errors & error codes

Every Finance API response uses the same envelope, so you can handle success and failure uniformly.

Response envelope

A successful response sets success: true and carries the payload in result (list endpoints also include a pagination object):

Success

{ "success": true, "result": { "id": "..." } }

A failure sets success: false and returns one or more errors, each with a stable code and a human-readable message:

Error

{
  "success": false,
  "errors": [
    { "code": "invalid-request", "message": "The request contains invalid parameters." }
  ]
}

Branch on the code, not the message — messages may change, codes are stable.

Standard errors

These apply across endpoints:

HTTP	`code`	When it happens	What to do
`400`	`invalid-request`	Malformed body or invalid parameters.	Fix the request; don’t retry it unchanged.
`401`	`unauthenticated`	Missing or expired token.	Refresh the token and retry — see Authentication.
`403`	`forbidden`	The operation isn’t available to your company setup.	Contact Venly to enable it.
`404`	`<resource>-not-found`	The resource (or one it references) doesn’t exist — e.g. `account-not-found`, `transfer-not-found`.	Check the ID; for transfers, confirm the account is the sender or receiver.
`409`	`concurrent-modification`	Stale `version` on an update.	Re-fetch, reapply your change, retry — see Versioning.
`422`	`idempotency-conflict` / (varies)	An idempotency key was reused with a different body, or replays a call that originally failed; or a semantically invalid input.	Branch on the `code`; to retry a genuine failure, use a new idempotency key.
`500`	`internal-error`	Unexpected server error.	Retry with backoff; if it persists, contact Venly.

Verification & activation gates

A new account can’t move money until it’s verified, and a self-custody wallet can’t until its permit confirms. These gates return different codes per operation — treat any of them as “not ready yet” rather than matching a single code:

Operation	HTTP	`code`
Create a virtual bank account	`400`	`kyc-not-verified`
Create a pay-in session	`422`	`kyc-required`
Request a pay-out	`400`	`account-not-active`
Create a pay-out route	`422`	`recipient-not-authorized` / `recipient-role-inactive`
Transfer/payment on an inactive self-custody wallet	`400`	`account-wallet-not-active`

See Account verification and Approving transfers without gas.

Verification errors

Verification-provisioning calls — minting a link, forwarding a sumsubToken, and provisioning a virtual bank account — can also fail on the platform itself:

HTTP	`code`	Retryable	Meaning
`409`	`verification-not-provisioned`	No	Your company has no provisioned verification tenant. Contact Venly.
`409`	`party-already-verified`	No	Nothing to do; the party is already `VERIFIED`.
`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`	`SUMSUB_TOKEN_NOT_REDEEMABLE`	Yes, with a fresh token	The share token is expired or already used. The whole account-creation transaction is rolled back.
`500`	`identity-verification-rejected`	No	The platform rejected the request itself. Contact support.
`503`	`identity-verification-unavailable`	Yes	The platform was unreachable. Retry with backoff.

See Troubleshooting verification for the retryable/terminal split on each of these.

Pay-out errors

Pay-out routes and pay-outs add these:

HTTP	`code`	When it happens
`409`	`route-already-exists`	A route already exists for this account, bank account and deposit asset.
`422`	`route-not-active`	The route hasn’t reached `ACTIVE`, or was `REJECTED`.
`422`	`route-unresolved`	The route doesn’t belong to this account.
`422`	`recipient-not-authorized`	The bank account’s party lacks a `PAYOUT_RECIPIENT` role on this account, or its KYC/KYB isn’t cleared.
`422`	`recipient-role-inactive`	The `PAYOUT_RECIPIENT` role exists but is `INACTIVE`.
`422`	`unsupported-asset`	The deposit asset or route lane isn’t enabled for your tenant.
`422`	`unsupported-combination`	No single provider resolves for that bank account and deposit asset.
`400`	`invalid-account-number` / `invalid-routing-number` / `invalid-account-type` / `invalid-bank-address`	Rail credentials failed validation when registering a payout bank account.

A pay-out request that returns 201 can still fail. Allowance and balance are not pre-checked, so an underfunded pay-out lands in FAILED with a failureReason instead of erroring at request time — see Pay-outs.

Rate limits

The Finance API doesn’t publish fixed numeric rate limits. Build for resilience regardless:

Cache your access token and reuse it until it nears expiry — don’t fetch one per request.
Back off and retry on 500 (and on 429, if returned), using exponential backoff with jitter.
Make retries safe with an idempotency key so a replay never double-charges.

If you expect high call volumes, confirm current limits with your Venly contact — they aren’t enumerated in the API contract.

Next steps

API conventions

Idempotency, pagination, and versioning rules.

Account verification

The most common reason an otherwise-correct request is rejected.

Troubleshooting verification

Every verification error code, and how to tell a stall from a failure.

Webhooks

Catch asynchronous failures that no HTTP response can tell you about.

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

Response envelope

Standard errors

Verification & activation gates

Verification errors

Pay-out errors

Rate limits

Next steps

API conventions

Account verification

Troubleshooting verification

Webhooks

​Response envelope

​Standard errors

​Verification & activation gates

​Verification errors

​Pay-out errors

​Rate limits

​Next steps

API conventions

Account verification

Troubleshooting verification

Webhooks

Response envelope

Standard errors

Verification & activation gates

Verification errors

Pay-out errors

Rate limits

Next steps