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

# Idempotency

## What is idempotency?

Idempotency is a property of an API operation that guarantees making the same request multiple times has the same effect as making it once.
If a request is sent, and then sent again, whether due to a network timeout, a retry, a duplicate click, or a client crashing before it
received a response, the server processes it safely without creating duplicate side effects.

## How is the MijnKlantportaal API handling idempotency?

The API supports idempotency for `POST`, `PUT` and `PATCH` operations. We will ignore the header if you provide it in any other HTTP-operation.
The given key can then still be used. You can provide an idempotency key via the `Idempotency-Key` header. Our recommendation is to use
UUIDv4 strings as key. Idempotency keys are linked to API keys, so the same key can be used over multiple API authentication tokens.

If you provide a correct and unique idempotency key, the API request will be handled as expected. When the API returns a non-successful response,
the key will not be saved and so can be used again. If the first requests was successful and you provide the same payload with the same key again
then the API will return the same response with an additonal header: `Idempotency-Replayed: true`. If you provide the same key with a different body,
the request will be rejected.

Idempotency keys will be saved for **90 days** (3 months). After this window, the same key can be used again.

<Tip>Keep in mind that idempotency keys can be at maximum 255 characters long. Longer keys will be rejected.</Tip>

## Request example

```bash Example of creating customer theme={null}
curl --request POST \
  --url https://api.mijnklantportaal.nl/v1/customers \
  --header 'Authorization: Bearer apikey_abc123...' \
  --header 'Idempotency-Key: 4901453f-2567-4b93-a6c7-042262dcb6d3' \
  --header 'Content-Type: application/json' \
  --data '
        {
            "companyName": "Test Company BV",
            "address": "Teststreet 123",
            "zipCode": "1234AB",
            "city": "Amsterdam",
            "primaryEmail": "john.doe@test.com",
            "countryCode": "NL"
        }
    '
```

## Response examples

**Using the same idempotency key for the same request**

```http HTTP theme={null}
Content-Type: application/json
Idempotency-Key: 4901453f-2567-4b93-a6c7-042262dcb6d3
Idempotency-Replayed: true

{
    // The same response as the first request
    ...
}
```

**Using the same idempotency key for another request**

```json 409 - Conflict theme={null}
{
    "code": 409,
    "message": "The given Idempotency-Key is already used for another request."
}
```

**Giving a too long idempotency key**

```json 400 - Bad Request theme={null}
{
    "code": 400,
    "message": "The Idempotency-Key can not be longer than 255 characters, yours has 300 characters. We recommend using UUIDv4 strings."
}
```