Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.velobase.io/llms.txt

Use this file to discover all available pages before exploring further.

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