Idempotency, pagination, and versioning rules that apply to every Venly API endpoint.
These conventions apply uniformly across the Fundflow API and Finance API. Endpoint references link here rather than restating the rules — bookmark this page.
PATCH updates (use the version field for optimistic locking)
Virtual bank account creation
DELETE requests
Fiat-to-crypto payment sessions
Store the key client-side until you receive a 2xx. If your process crashes mid-flight, the same key on retry guarantees the request lands at most once.
Idempotency keys are bound to the exact request body. Don’t reuse a key across requests with different amounts or recipients — that returns 422, not the original response.
Iterate using hasNextPage, not by computing pageNumber * pageSize >= numberOfElements. The total count can shift between requests; the boolean is authoritative.
Breaking changes ship in a new major version (e.g. /v2). The old version stays live throughout the deprecation window.
Breaking
Non-breaking (ships within the current version)
Removing a field from a response
Adding a new field to a response
Renaming a field
Adding a new optional request field
Changing a field’s type
Adding a new endpoint
Making an optional input required
Adding a new enum value
Removing an endpoint
Adding a new error code
Renaming or removing an enum value
Tightening a previously undocumented validation
Treat unknown enum values gracefully. New enum values are not breaking — your client should ignore values it doesn’t recognise rather than throwing. This is the most common cause of integrations failing on minor releases.
