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.

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

Request example

Example of creating customer

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

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

409 - Conflict

{
    "code": 409,
    "message": "The given Idempotency-Key is already used for another request."
}

Giving a too long idempotency key

400 - Bad Request

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

Getting started

AI

OAuth

CMS

What is idempotency?

How is the MijnKlantportaal API handling idempotency?

Request example

Response examples

​What is idempotency?

​How is the MijnKlantportaal API handling idempotency?

​Request example

​Response examples

What is idempotency?

How is the MijnKlantportaal API handling idempotency?

Request example

Response examples