we are trying to integrate Google agentic commerce agents using apigeex & there was a request from Google team to use Idempotency-Key in apigeex to ensure duplicate operations doesn’t happen during re-tries. Is it a best practice to implement idempotency in apigeex? Is there a sample implementation that we could reference? Also are there any limitations with using idempotency in apigeex since apigeex must use the cache the requests/responses for POST/PATCH HTTP methods for 24hrs? Is there any call volume limitation for this use case per org or by environment?
Hi @raghunathapalle, I noticed your question hasn’t been answered yet. Don’t worry—we’ll keep an eye on it and try to get some input from other members soon.
In the meantime, you’re invited to join our Community Tech Talk happening this thursday, March 19: Mobile Device Flow implementation for Apigee X/Hybrid 
Register here!
Hi @raghunathapalle,
Yes, implementing idempotency in Apigee X is a best practice for this UCP integration, because the UCP cart REST spec says state-changing operations should support idempotency, and when Idempotency-Key is provided, the server must store the key/result for at least 24 hours, return the cached result for duplicate keys, and return 409 Conflict if the same key is reused with different parameters.
For sample implementation, the right Apigee pattern is LookupCache + PopulateCache, not ResponseCache. Google’s Apigee docs describe LookupCache and PopulateCache as the policies for general-purpose caching.
Recommended pattern:
-
Cache key: {client}:{method}:{path}:{Idempotency-Key}
-
Cache value: request fingerprint/hash, processing state (inflight / completed), and stored response or response reference
-
Behavior:
-
no cache entry → process request, then store result
-
same key + same payload → return stored result
-
same key + different payload → return 409
-
On limitations, yes, there are important ones:
- 24 hours is supported in Apigee cache; cache expiration can be 1 second to 30 days.
- Cache limits include 2 KB key size, 256 KB value size, 10 million items per cache, and 100 caches per environment.
- The biggest architectural caveat is that Apigee cache is eventually consistent, so it should not be treated as a strict exactly-once mechanism under concurrent retries. Google’s own guidance says designs that depend on strict cache consistency can see unexpected behavior.
So the practical answer is:
- Yes, idempotency in Apigee X is the right edge-layer best practice.
- Yes, there is a reference pattern: LookupCache + PopulateCache with request fingerprinting.
- Yes, 24-hour retention is feasible.
- Yes, there are limitations: cache size/entry limits and eventual consistency.
- On call-volume limits, I did not find a published hard runtime limit specifically for idempotency cache lookups/populates per org or environment in current Apigee docs; the documented limits are on cache resources and sizes, not a separate per-second cap for this pattern.
This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.