Skip to main content
Network issues can cause an API request to drop the response, even if Velobase successfully processed it. To prevent double charges when you retry a request, Velobase APIs require an idempotency identifier.

​
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 balance 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.
EndpointFieldPurpose
POST /v1/billing/depositidempotency_keyA unique string (like a UUID) generated by your system for this specific deposit.
POST /v1/billing/deduct, POST /v1/billing/freeze, POST /v1/billing/consume, POST /v1/billing/unfreezetransaction_idThe unique ID of the task or job in your system that caused the billing event.

​
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): 
{
  "error": {
    "message": "transactionId already belongs to another customer",
    "type": "conflict",
    "code": "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).