Overview#
Idempotency ensures that making the same request multiple times produces the same result as making it once. This is critical for financial operations, preventing duplicate transactions, charges, or resource creation when network issues, timeouts, or client retries occur.The Kobble API uses idempotency keys to provide this protection. When you include an idempotency key with your request, the API caches the response and returns the same result for any subsequent requests using the same key.Why Idempotency Matters#
Common Scenarios#
1.
Network Timeouts: A request succeeds on the server but your application never receives the response
2.
Automatic Retries: Your application automatically retries failed requests
3.
User Actions: Users clicking submit buttons multiple times
4.
Distributed Systems: Multiple services or instances attempting the same operation
Multiple resource creation
Benefits#
Reliability: Safely retry requests without side effects
Consistency: Guaranteed same result for identical requests
User Experience: Prevents accidental duplicate operations
Financial Safety: Critical for payment and transaction operations
How It Works#
When you send a request with an idempotency key:1.
First Request: The API processes your request and caches the response
2.
Subsequent Requests: If you retry with the same key, the API returns the cached response instead of processing again
3.
Key Matching: The same key must be used with the same endpoint and request data
Usage#
All POST endpoints that support idempotency require the Idempotency-Key header:Format: Must be a valid UUID v4 (e.g., 550e8400-e29b-41d4-a716-446655440000)Generating Idempotency Keys#
Generate a unique UUID for each distinct operation you want to perform.Example (TypeScript/Node.js):DO: Generate a new UUID for each unique operation
DO: Reuse the same UUID when retrying the exact same request
DO: Store the idempotency key with your request data
DO NOT: Reuse the same UUID for different operations
DO NOT: Use sequential or predictable values
DO NOT: Use the same key across different endpoints
Response Behavior#
First Request#
When you send a request with a new idempotency key:Status: Returns the normal endpoint status code (e.g., 201 Created for POST endpoints, 200 OK for PATCH endpoints)
Behavior: Request is processed and response is cached
Response: Contains the result of the operation
Subsequent Requests (Same Key)#
When you retry with the same idempotency key:Behavior: Cached response is returned immediately
Response: Same response as the original request
Response Types#
The API caches different types of responses:1.
Success Responses: The successful result of your operation
2.
Error Responses: If the original request failed, the same error is returned
3.
Processing Status: If the original request is still processing, a processing status is returned
Supported Endpoints#
The following endpoints support idempotency:Transactions#
POST /api/transactions - Create transaction
POST /api/transactions/manual-credit - Manual credit
POST /api/transactions/manual-debit - Manual debit
Cards#
POST /api/cards - Create card
POST /api/cards/:id/secrets - Generate time-based secret
POST /api/cards/:id/:action - Renew or replace card
Response Status Codes#
| Status Code | Meaning | When It Occurs |
|---|
201 Created | Resource created successfully | First request (for POST endpoints) |
200 OK | Request processed successfully | First request (for PATCH endpoints) |
202 Accepted | Cached response returned | Subsequent requests with same key |
400 Bad Request | Invalid idempotency key usage | Key used with different endpoint or missing |
4xx/5xx | Original error status code | Cached error response |
Key Characteristics#
Caching Duration#
Idempotency keys are valid for 24 hours from the first request
After 24 hours, the key expires and can be reused (though we recommend generating a new key)
Request Matching#
The API matches requests based on:1.
Idempotency Key: Must be identical
2.
Endpoint Path: Must match exactly (prevents key reuse across endpoints)
3.
Request Data: Should be identical (though the API primarily matches on key and endpoint)
Concurrent Requests#
If multiple requests with the same idempotency key arrive simultaneously:First request: Processes normally and returns the normal endpoint status code (e.g., 201 Created)
Subsequent requests (while processing): Return 202 Accepted with processing status
Subsequent requests (after completion): Return 202 Accepted with the cached result
Best Practices#
1. Always Include Idempotency Keys#
Include an idempotency key for all POST requests to idempotent endpoints. This protects against:2. Generate Unique Keys Per Operation#
Each distinct operation should have its own idempotency key:3. Retry Strategy#
When retrying failed requests, use the same idempotency key:4. Handle Timeouts#
If a request times out, retry with the same idempotency key:5. Key Management#
Store keys: Keep idempotency keys with your request data for retry scenarios
Log keys: Include keys in your logs for debugging
Don't reuse: Generate new keys for different operations, even if the data is similar
6. Error Handling#
If you receive a cached error response, the original request failed
Review the error message to understand what went wrong
Fix the underlying issue before retrying
You may need a new idempotency key if you're changing the request data
Limitations#
1.
POST Requests Only: Currently only POST requests support idempotency
2.
24-Hour Window: Keys expire after 24 hours
3.
Endpoint-Specific: Keys are tied to specific endpoints and cannot be reused across different endpoints
4.
Request Matching: Keys are matched per endpoint, so the same key cannot be used for different endpoints
Modified at 2025-12-05 11:07:36
