Skip to main content

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.

​
HTTP Error Reference

​
400 Bad Request

The request body or parameters failed validation. Common causes:
  • Missing required fields
  • Invalid field format (e.g. wrong UUID format, unsupported enum value)
  • Finance API endpoint requiring idempotencyKey called without it in the request body
Check the errors array in the response body for field-level details: 
{
  "success": false,
  "errors": [
    { "code": "REQUIRED_FIELD", "field": "fiatCurrencyId", "message": "Field is required" }
  ]
}

​
401 Unauthorized

The Bearer token is missing, expired, or malformed. 
{ "success": false, "errors": [{ "code": "UNAUTHORIZED" }] }
Fix: Re-authenticate using the token endpoint and retry the request with the new token. Implement proactive refresh — request a new token ~30 seconds before the 5-minute expiry rather than waiting for a 401.

​
403 Forbidden

The token is valid but the caller lacks permission for this operation. Common causes:
  • User role is insufficient (e.g. COMPANY_VIEWER attempting to create a ramp request)
  • Company KYB status is not VERIFIED — required before creating ramp requests
  • Resource belongs to a different company
Fix: Check the role assigned to the credentials you are using, and verify GET /v1/company returns kybStatus: "VERIFIED".

​
404 Not Found

The requested resource does not exist. Common causes:
  • Incorrect or stale ID in the URL path
  • Resource was deleted
Fix: Verify the ID against a list endpoint (GET /v1/ramp-requests, GET /v1/company-wallets, etc.) to confirm the resource exists.

​
409 Conflict — Optimistic Lock

A concurrent modification was detected. Another process updated the resource between your read and write. 
{
  "success": false,
  "errors": [{ "code": "OPTIMISTIC_LOCK_EXCEPTION", "message": "..." }]
}
Fix: Fetch the resource again (GET /v1/ramp-requests/{id}), read the current version, apply your change with the new version, and retry.

​
422 Unprocessable Entity (Finance API)

An idempotencyKey value was reused with a different request body. Fix: Generate a new UUID for the new logical request. Only reuse a key when retrying the exact same operation after a network failure.

​
500 Internal Server Error

An unexpected error occurred on the server. Fix: Retry with exponential backoff. If the error persists, contact us with the request timestamp and any request ID from the response headers.

​
Common Integration Issues

​
Ramp request stuck in AWAITING_FUNDS

On-ramp: Confirm the bank transfer was sent for the exact amount specified, and that the unique payment reference was included. Missing the reference is the most common cause — the payment cannot be matched without it. Off-ramp: Confirm the transaction hash has been submitted via PATCH /v1/ramp-requests/{id}/tx-hash, and that the blockchain transaction is confirmed (check a block explorer). Processing begins only after on-chain confirmation.

​
Ramp request not moving to PROCESSING

  • Blockchain congestion can delay confirmation — check the transaction status on a block explorer before contacting us.
  • For on-ramp, bank transfers can take 1-2 business days depending on the payment network. SEPA same-day cut-offs apply.

​
Cannot create a ramp request

  • GET /v1/company must return kybStatus: "VERIFIED".
  • The bank account or wallet used must have verificationStatus: "VERIFIED". Accounts in PENDING status are not eligible.
  • Check your user role — COMPANY_VIEWER cannot create requests.

​
Wallet verification not completing (Fundflow)

Wallet ownership verification requires completing the verification process after submitting the wallet address. Contact us if the status has not moved from PENDING after the process is complete.

​
409 on every update attempt

You are sending a stale version. Always read the resource immediately before writing to get the current version — do not cache or hardcode version numbers.

​
Contacting Support

General Support

Get in touch — response within 24 hours

Security Issues

Get in touch — response within 2 hours
When contacting support, include:
  • Your company ID
  • The affected resource ID (ramp request, wallet, etc.)
  • The exact error response body
  • Timestamps of the failed requests

Security Guide

Credential and token best practices

Quick Reference

Status codes and endpoint list

Glossary

Status values and terminology