> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Prevent duplicate request processing with idempotency keys

## 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

| Aspect                 | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| **Cache-Based**        | Uses an in-memory cache to store request results                     |
| **TTL**                | Cached responses expire after 1 hour (3600 seconds)                  |
| **UUID Validation**    | Idempotency keys must be valid UUIDs                                 |
| **Automatic Response** | Returns 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 Name         | Required | Format        | Example                                |
| ------------------- | -------- | ------------- | -------------------------------------- |
| `idempotency-key`   | No       | Valid UUID v4 | `550e8400-e29b-41d4-a716-446655440000` |
| `x-idempotency-key` | No       | Valid UUID v4 | `550e8400-e29b-41d4-a716-446655440000` |

## Usage Guidelines

### When to Use Idempotency Keys

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

### Behavior

| Scenario               | Result                                                  |
| ---------------------- | ------------------------------------------------------- |
| **First Request**      | Processes normally and caches the response              |
| **Duplicate Requests** | Returns the cached response immediately (within 1 hour) |
| **After TTL Expiry**   | Processes as a new request after 1 hour                 |

### Error Handling

| Error               | Response                                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| Invalid UUID Format | `400 Bad Request` with message: "Invalid idempotency key format. The idempotency-key must be a valid UUID" |
| Missing Key         | Request processes normally without idempotency                                                             |

## Example Usage

### Request with Idempotency Key

```bash theme={null}
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:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const uuid = crypto.randomUUID();
  ```

  ```python Python theme={null}
  import uuid
  key = uuid.uuid4()
  ```

  ```bash Postman theme={null}
  {{$guid}}
  ```
</CodeGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Generate Unique Keys" icon="fingerprint">
    Use a fresh UUID for each logical operation
  </Card>

  <Card title="Client-Side Generation" icon="laptop">
    Generate UUIDs on the client side before making requests
  </Card>

  <Card title="Retry Logic" icon="arrows-rotate">
    Use the same idempotency key when retrying failed requests
  </Card>

  <Card title="Key Management" icon="key">
    Don't reuse keys across different operations
  </Card>
</CardGroup>

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

<Info>
  This implementation ensures reliable API operations and prevents duplicate processing in distributed systems and unreliable network conditions.
</Info>