Why does Membrane API Gateway return 409 Conflict with has already been processed?

The idempotency plugin has already seen the idempotency key of the request within the expiration time. The request is treated as a duplicate and rejected.

How long does Membrane remember idempotency keys?

For the number of seconds set in expiration, 3600 by default. Keys are kept in memory per plugin instance, so they are lost on restart and not shared between gateway nodes.

Does production mode hide the details of idempotency errors?

No. The idempotency plugin always sends the detail, including the key, and the link to the documentation, even when Membrane runs in production mode.

409 Conflict: Idempotency Key Already Processed

Membrane API Gateway returns 409 Conflict with a link to this page when the idempotency plugin finds that the idempotency key of a request was already seen within the expiration time. The client sent a duplicate. This is the intended behavior of the plugin, not an error of the gateway.

The Error Response

The response contains the status 409 Conflict, the detail key ... has already been processed with the key, the problem type https://membrane-api.io/problems/user and a link to this page. The type user means that the request caused the problem.

What the Idempotency Plugin Does

The idempotency plugin protects the backend from processing the same operation twice, for example a payment that a client retries after a timeout. It evaluates the key expression on each request. The first request with a key passes; every further request with the same key is rejected until the key expires after expiration seconds.

api:
  port: 2000
  flow:
    - idempotency:
        language: jsonpath
        key: $.id
        expiration: 86400
  target:
    url: https://api.predic8.de

api:
  port: 2000
  flow:
    - idempotency:
        language: jsonpath
        key: $.id
        expiration: 86400
  target:
    url: https://api.predic8.de

Common Causes

The Client Retried a Request

The client repeated a request with the same idempotency key, for example after a timeout or a network error. The first request may well have succeeded.

An Earlier Attempt Failed

Membrane records every key the first time it sees it, whatever the outcome of that request. If the first request failed or was aborted, a retry with the same key is still rejected.

The Key Is Not Unique

Different requests produce the same key, because the key expression does not select a value that is unique per operation, for example a field that is constant or missing.

How to Fix It

Client: generate a new, unique key for each new operation, and reuse a key only for real retries of the same operation.
Operator: check that the key expression and its language extract a unique value, for example a request header or a body field such as $.id.
Operator: adjust expiration (in seconds, default 3600) if keys must be accepted again sooner.

Keys are kept in memory per plugin instance. They are lost when the gateway restarts and are not shared between several gateway nodes.

Details in Production Mode

Unlike most errors, this error is sent with the detail and the link to this page even when Membrane runs in production mode. Setting production: true in the configuration document does not remove them. The detail contains the key that the client sent.