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

# Idempotency

> Learn how to safely retry POST requests without creating duplicate resources using idempotency keys.

## Overview

Network failures, timeouts, and other transient issues can cause your application to retry requests without knowing whether the original request succeeded. This can lead to duplicate resources being created in the target system.

The Maesn API supports idempotency for POST requests, allowing you to safely retry operations without creating duplicates. By including an `idempotency-key` header, the API guarantees that multiple identical requests will have the same effect as a single request.

## How it works

When you send a POST request with an `idempotency-key` header:

1. **First request**: The API processes the request normally and caches the response
2. **Subsequent requests with the same key**: The API returns the cached response without re-executing the operation
3. **Same key with different body**: The API returns an error (the key cannot be reused for different data)

Idempotency keys are scoped to your tenant and user, so different users can safely use the same key values.

## Supported endpoints

| Endpoint                                                                                                             | Supported systems                                                                                        |
| :------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
| [`POST /bookingProposals`](/api-reference/accounting-endpoints/bookingproposals/create-booking-proposal)             | Lexware Office, Microsoft Business Central, Procountor, Sage Accounting, Snelstart, Visma Economic, Xero |
| [`POST /bookingProposals/async`](/api-reference/accounting-endpoints/bookingproposals/create-booking-proposal-async) | DATEV Unternehmen Online                                                                                 |

## Using the idempotency key

Include the `idempotency-key` header in your POST request:

```bash theme={null}
curl -X POST "https://api.maesn.dev/accounting/bookingProposals" \
  -H "X-API-KEY: your-api-key" \
  -H "X-ACCOUNT-KEY: your-account-key" \
  -H "idempotency-key: order-12345-invoice-001" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@invoice.pdf"
```

## Response behavior

| Scenario                                            | Response                                             |
| :-------------------------------------------------- | :--------------------------------------------------- |
| First request with a new key                        | Normal response (201 for sync, 202 for async)        |
| Retry with same key and same body                   | Cached response returned (same status code and body) |
| Same key with different body                        | 422 error                                            |
| Same key while original request is still processing | 409 error                                            |

## Error codes

### 409 Conflict - Request still processing

If you retry a request while the original is still being processed, the API returns a 409 error to prevent race conditions.

**What to do**: Wait and retry after a short delay. The original request should complete shortly.

### 422 Unprocessable Entity - Key reused with different body

If you send a request with an idempotency key that was already used for a different request body, the API returns a 422 error.

**What to do**: Use a new, unique idempotency key for the new request.

## Best practices

### Generating keys

Use a value that uniquely identifies the logical operation you're performing. Good approaches include:

* **UUIDs**: `550e8400-e29b-41d4-a716-446655440000`
* **Business identifiers**: `order-12345-invoice-001`
* **Composite keys**: `{user-id}-{document-id}`

The key can be any string value. We recommend using descriptive identifiers when possible, as they make debugging easier.

### When to use idempotency keys

* **Always** for production POST requests where duplicates would cause problems, for example capturing external invoices or creating journal entries
* **Especially** when implementing retry logic for failed requests
* **When** network conditions are unreliable

### Key expiration

Idempotency keys are valid for 24 hours after the first request completes. After this period, the same key can be reused for a new request.

<Warning>
  Do not rely on key expiration as part of your normal workflow. Always generate unique keys for distinct operations.
</Warning>