# Idempotency for SOAP APIs
source: https://developer.mastercard.com/iccp/documentation/api_basics/idempotency/idempotency-soap/index.md

Idempotency is a key concept, referring to certain operations that can be performed multiple times without changing the result beyond the initial execution. In the context of SOAP APIs, an API is considered idempotent when making multiple identical requests produce the same effect as making a single request.

To achieve idempotency, you should send an `Idempotency-Key` header that is unique to each request. The server uses this header, user ID, along with the request body, to identify subsequent retries of the same request.

The mechanism is intended to work for all `POST` and `PATCH` methods. The `Idempotency-Key` is optional. If the header is not specified in the request, the request will be processed in the standard way.

If you send an `Idempotency-Key` in the request, then the application checks if this key/request is received.

* If the key is not found in the database, the API call is processed in a standard way according to the method's handling algorithm. When the processing is complete, the `Idempotency-Key` and the request and response bodies are stored in the database.
* If the `Idempotency-Key` of the request is already in the database, it additionally verifies the request body. If they are the same, it retrieves the response from the database and returns it.   

The idempotency keys are automatically removed from the application after the stipulated time period.

* ICCP SOAP APIs have a time-to-live (TTL) of 300 seconds. If a request using a previous `Idempotency-Key` is retried after this period, it will be treated as a new request.
* If a request is retried with the same `Idempotency-Key` before the original request finishes processing with a previous, the API will reject the request with one of the following error messages:

## Sample error messages for API response {#sample-error-messages-for-api-response}

### Error message-1 {#error-message-1}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope
    xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
        <ns2:getPurchaseRequestDetail
            xmlns:ns1="http://mastercard.com/sd/pc/service"
            xmlns:ns2="http://mastercard.com/sd/pc2/service">
            <ns2:purchaseRequestId>0</ns2:purchaseRequestId>
            <ns2:errorMessage>
                <ns2:errorCode>REQ_DUP</ns2:errorCode>
                <ns2:errorDescription>
                    Duplicate Request Detected. A request with a similar idempotent key is already in progress. Please try again later or use a new idempotent key.
                </ns2:errorDescription>
            </ns2:errorMessage>
        </ns2:getPurchaseRequestDetail>
    </s:Body>
</s:Envelope>
```

### Error message-2 {#error-message-2}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope
    xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
        <ns2:getPurchaseRequestDetail
            xmlns:ns1="http://mastercard.com/sd/pc/service"
            xmlns:ns2="http://mastercard.com/sd/pc2/service">
            <ns2:purchaseRequestId>0</ns2:purchaseRequestId>
            <ns2:errorMessage>
                <ns2:errorCode>VEIDMK</ns2:errorCode>
                <ns2:errorDescription>
                    Idempotent key is empty/invalid on the request header.
                </ns2:errorDescription>
            </ns2:errorMessage>
        </ns2:getPurchaseRequestDetail>
    </s:Body>
</s:Envelope>
```