Prevents duplicate request processing based on a dynamic idempotency key.

This interceptor evaluates an expression (e.g., from headers or body) to extract an idempotency key. If the key has already been processed, it aborts the request with a 409 response.

Useful for handling retries from clients to avoid duplicate side effects like double payment submissions.

Syntax

idempotency:
  key: <string> # required
  '$ref': <string>
  expiration: <number>
  language: groovy
  xmlConfig: {}

idempotency:
  key: <string> # required
  '$ref': <string>
  expiration: <number>
  language: groovy
  xmlConfig: {}

Attributes

Name	Required	Default	Description	Examples
$ref	false	-	Reference a component defined under components.	-
expiration	false	3600	Time in seconds after which idempotency keys automatically expire. Useful to avoid memory leaks in long-running systems. Common values: 300 seconds = 5 minutes 86400 seconds = 1 day 604800 seconds = 1 week 2592000 seconds = 1 month (30 days)	-
key	true	-	Expression used to extract the idempotency key from the exchange. Can be an XPath, JSONPath, header, or other supported syntax depending on the language.	$.id
language	false	SpEL	the language of the 'test' condition	SpEL, groovy, jsonpath, xpath

Child Structure

Element	Cardinality	Description
xmlConfig	0..1

Can be used in

abort api case chain components for global if interceptor internal otherwise proxy registration request response serviceProxy soapProxy stompProxy time transport wsStompReassembler