{"templateId":"markdown","versions":[{"version":"v1","label":"v1","link":"/pt-br/products/collections/guides/idempotency","default":true,"active":true,"folderId":"3a2d3fa8"},{"version":"v0","label":"v0","link":"/pt-br/products/collections/v0/guides/idempotency","default":false,"active":false,"folderId":"3a2d3fa8"}],"sharedDataIds":{"sidebar":"sidebar-@l10n/pt-BR/products/collections/@v0/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Retry requests safely with idempotency keys","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"retry-requests-safely-with-idempotency-keys","__idx":0},"children":["Retry requests safely with idempotency keys"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a client supplies a unique key (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Idempotency-Key"]},", UUID). The header is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]},":"," ","if it is omitted the request is processed"," ","normally  (no deduplication, no replay). Supplying the header is strongly recommended for POST"," ","operations that create side effects."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provide optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Idempotency-Key"]}," on POST writes for safe retries:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Success → cached and replayable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In-flight duplicate → 409 (retry later)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mismatch → 422."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Failure → entry removed (safe retry)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Only successes are replayed."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"with-vs-without-the-header","__idx":1},"children":["With vs Without the Header"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Idempotency-Key"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["First request claims and (if successful) caches response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Concurrent duplicates while in flight receive 409 + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After: 1"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Later identical retries get the cached 2xx response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Different payload/path/method using same key → 422 mismatch."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Without the header:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Filter bypasses idempotency entirely."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each call executes independently; duplicates may create repeated side effects."]}]}]},"headings":[{"value":"Retry requests safely with idempotency keys","id":"retry-requests-safely-with-idempotency-keys","depth":1},{"value":"With vs Without the Header","id":"with-vs-without-the-header","depth":3}],"frontmatter":{"tocMaxDepth":3,"seo":{"title":"Retry requests safely with idempotency keys"}},"lastModified":"2026-10-07T18:01:23.000Z","isTranslationFallback":true,"pagePropGetterError":{"message":"","name":""}},"slug":"/pt-br/products/collections/guides/idempotency","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}