Skip to main content

​
Overview

This API implements idempotency for specific endpoints to prevent duplicate request processing. Idempotency ensures that making the same request multiple times has the same effect as making it once, which is crucial for operations like creating entities or sending invitations.

​
How It Works

AspectDescription
Cache-BasedUses an in-memory cache to store request results
TTLCached responses expire after 1 hour (3600 seconds)
UUID ValidationIdempotency keys must be valid UUIDs
Automatic ResponseReturns cached response for duplicate requests without re-processing

​
Supported Endpoints

The following endpoints support idempotency:
  • POST /downstream-entities/onboarding/invite
  • POST /downstream-entities/onboarding/add

​
Headers

Include one of these headers in your requests to enable idempotency:
Header NameRequiredFormatExample
idempotency-keyNoValid UUID v4550e8400-e29b-41d4-a716-446655440000
x-idempotency-keyNoValid UUID v4550e8400-e29b-41d4-a716-446655440000

​
Usage Guidelines

​
When to Use Idempotency Keys

Creating new entities or resources
Sending invitations or notifications
Any operation that should not be duplicated
Network retry scenarios
User interface double-click prevention

​
Behavior

ScenarioResult
First RequestProcesses normally and caches the response
Duplicate RequestsReturns the cached response immediately (within 1 hour)
After TTL ExpiryProcesses as a new request after 1 hour

​
Error Handling

ErrorResponse
Invalid UUID Format400 Bad Request with message: “Invalid idempotency key format. The idempotency-key must be a valid UUID”
Missing KeyRequest processes normally without idempotency

​
Example Usage

​
Request with Idempotency Key

POST /downstream-entities/onboarding/invite
Content-Type: application/json
idempotency-key: 550e8400-e29b-41d4-a716-446655440000

{
  "email": "user@example.com",
  "entityName": "Example Corp"
}

​
Generating UUIDs

Use any UUID v4 generator: 
const uuid = crypto.randomUUID();

​
Best Practices

Generate Unique Keys

Use a fresh UUID for each logical operation

Client-Side Generation

Generate UUIDs on the client side before making requests

Retry Logic

Use the same idempotency key when retrying failed requests

Key Management

Don’t reuse keys across different operations

​
Testing

Include both scenarios in your tests:
  • Requests with idempotency keys
  • Requests without idempotency keys

​
Postman Variables

You can use Postman’s built-in variable for testing: 
{{$guid}}
This generates a new UUID for each request, or create a collection variable for consistent testing.
This implementation ensures reliable API operations and prevents duplicate processing in distributed systems and unreliable network conditions.