Skip to main content
Network issues can cause an API request to drop the response, even if Velobase successfully processed it. To prevent duplicate processing when you retry, Velobase’s billing primitives require an idempotency identifier.
Idempotency covers all three write surfaces: deposits use an idempotency_key body field, the billing primitives (freeze, consume, deduct, unfreeze) use your transaction_id, and model gateway calls (POST /v1/chat/completions, POST /v1/messages) use the optional Idempotency-Key request header.

​
How it works

When Velobase receives a request, it checks if the provided identifier has already been processed for that specific customer:
  1. First request: The operation is processed, the customer’s wallet is updated, and the result is returned with "is_idempotent_replay": false.
  2. Duplicate request: Velobase recognizes the identifier, skips the operation, and immediately returns the exact same result as the original request, but marked with "is_idempotent_replay": true.

​
Identifiers by Endpoint

Velobase uses different identifier fields depending on the operation type. These fields must be passed in the JSON request body. All amount fields on these requests are positive integer credits (1 USD = 1,000,000 credits).

​
Gateway calls: the Idempotency-Key header

Model gateway calls settle the customer wallet automatically, so their idempotency handle is a request header rather than a body field. Send Idempotency-Key: <unique-key> on POST /v1/chat/completions or POST /v1/messages:
  1. First request with a given key: the call is relayed and billed normally.
  2. Replay of the same key: the gateway returns 409 with a clear message instead of relaying the call again and double-charging the customer.
Use a fresh key for every new logical request, and reuse a key only when retrying the exact same request (for example after a network timeout where you never saw the response).

​
Error: Transaction Conflict

Identifiers are scoped to the customer (customer_id). If you attempt to reuse the exact same transaction_id or idempotency_key for a different customer, Velobase will reject the request with a 409 Conflict error (transaction_conflict):
Always ensure your identifiers are globally unique across your entire system, such as using a UUIDv4 or a composite key (user-123-task-456).