Idempotency

Create, Update and Delete APIs on Embarc accept the Idempotency-Key HTTP header so you can safely retry write operations without creating duplicate records (for example, when posting loan repayments or creating customers from a workflow engine).

How It Works

1. Generate a unique key (UUID is ideal) per business action.
2. Send the key with the request using the header Idempotency-Key: 5d6f7c8a-1b23-4cde-9fab-0123456789ab.
3. Embarc processes the command and stores the result against that key.
4. If you retry with the same key, Embarc instantly returns the cached response instead of re-running the command.

This applies to create and update endpoints like loan transactions, approvals, customer updates, configuration changes, etc. GET calls do not use idempotency.

Response Behaviour

• Duplicate success: You get the original success payload and HTTP status. The response includes Idempotent-Cache: true to indicate it came from the cache.
• Under processing: If a second request arrives before the first finishes, Embarc returns 425 Too Early. Retry after the initial call completes.
• Original failure: Embarc replays the same error payload so you know the command failed previously.

Best Practices

• One key per action: Never reuse a key for different operations. Treat it as a transaction identifier in your system.
• Store the mapping: Persist the key alongside your internal record so you can safely retry after timeouts.
• Pick a retention window: Embarc keeps idempotency records for a configurable period. Reuse the key only while the original action is still relevant.
• Log the response: Capture both the HTTP status and Idempotent-Cache header to confirm whether you hit the cache or executed a fresh command.

By supplying Idempotency-Key consistently, you protect your integration from network retries, user double-clicks, and other duplicate submissions.