Skip to main content
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:
HTTPcodeWhen it happensWhat to do
400invalid-requestMalformed body or invalid parameters.Fix the request; don’t retry it unchanged.
401unauthenticatedMissing or expired token.Refresh the token and retry — see Authentication.
403forbiddenThe operation isn’t available to your company setup.Contact Venly to enable it.
404account-not-foundThe resource (or one it references) doesn’t exist.Check the ID; for transfers, confirm the account is the sender or receiver.
409concurrent-modificationStale version on an update.Re-fetch, reapply your change, retry — see Versioning.
422(varies)Semantically invalid — e.g. unsupported currency pair, or insufficient balance/allowance.Fix the inputs; check the operation’s own notes.
500internal-errorUnexpected 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:
OperationHTTPcode
Create a virtual bank account400kyc-not-verified
Create a pay-in session422kyc-required
Create a payment request400account-not-active
Transfer/payment on an inactive self-custody wallet400account-wallet-not-active
See Account verification and Approving transfers without gas.

​
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.