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.
404<resource>-not-foundThe resource (or one it references) doesn’t exist — e.g. account-not-found, payment-request-not-found.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.
422idempotency-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.
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.

​
Payment request errors

Settling, reversing, and updating a payment request can return these in addition to the standard errors:
HTTPcodeWhen it happens
400invalid-amountAmount ≤ 0, or (on update) equal to the current amount.
400currency-mismatchcurrency doesn’t match the authorized currency.
402insufficient-fundsAccount wallet balance is below the upward adjustment delta.
402insufficient-allowanceSelf-custody allowance is below the upward adjustment delta.
403company-not-activeCompany isn’t ACTIVE (settlement and upward adjustments only).
404payment-request-not-foundNo payment request with that ID/reference for your company.
404account-not-foundNo account matches the supplied card-provider reference (by-reference endpoints).
409invalid-payment-statusThe request isn’t RESERVED, so it can’t be settled, reversed, or adjusted.
409modification-in-progressA previous adjustment or incremental authorization is still pending.
409wallet-not-activeA wallet involved in the operation isn’t ready — for self-custody, confirm the permit; otherwise the wallet’s amlStatus isn’t APPROVED yet.
422idempotency-conflictThe idempotencyKey was reused with a different body, or replays a call that originally failed.
wallet-not-active and the transfer/payment-create gate account-wallet-not-active describe the same condition — the account wallet isn’t ready to move funds. The exact code and HTTP status vary by endpoint, so treat any *-not-active code as “not ready yet” (see Account verification and, for self-custody, permits) rather than matching a single one.

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