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.
A key counts as processed as soon as its request arrives, also if processing it fails later, e.g. because the backend is not reachable. Further requests with that key are rejected until the key expires. To try again, the client has to use a new key.
The interceptor sees each request only once and cannot prevent Membrane's HTTP client from sending it again: a request with an idempotent method like GET, PUT or DELETE may be repeated after a read timeout, a reset connection or, if failover on 5xx is configured, a server error. If the backend does not handle these methods idempotently, disable retries of the HTTP client. POST and PATCH are only repeated when the connection could not be established, which is safe.
Retries are disabled in the global HTTP client configuration, which applies to all APIs:
configuration:
httpClientConfig:
retries:
retries: 0
Syntax
idempotency:
key: <string> # required
'$ref': <string>
expiration: <int>
language: groovy
maxKeys: <int>
xmlConfig: {}
idempotency:
key: <string> # required
'$ref': <string>
expiration: <int>
language: groovy
maxKeys: <int>
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:
| - |
| 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 | Scripting language used to evaluate the value expression. | SpEL | groovy | jsonpath | xpath |
| maxKeys | false | 10000 | Maximum number of keys that are remembered. When the limit is reached, the least recently used keys are dropped before they expire, and a request repeating a dropped key is no longer detected as a duplicate. Size it for the number of distinct keys expected within the expiration time, with headroom for peaks; clients sending many new keys can otherwise push out the keys of others. | 100000 |
Child Structure
| Element | Cardinality | Description |
|---|---|---|
| xmlConfig | 0..1 | XML namespace declarations for XPath expressions in the value. |