{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars/sdk_sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group","admonition"]},"type":"markdown"},"seo":{"title":"Idempotency and retries","description":"The specifications of Ratepay's APIs for easy payment transactions.","siteUrl":"https://docs.ratepay.com","keywords":"Ratepay developer portal, Ratepay api portal, Ratepay api reference docs","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"idempotency-and-retries","__idx":0},"children":["Idempotency and retries"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-sdk-does-not-retry-for-you","__idx":1},"children":["The SDK does not retry for you"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient"]}," operation retries automatically, every call makes exactly one HTTP request. If that"," ","request fails at the transport level or the server returns 5xx, you get a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayNetworkException"]}," and"," ","it's your integration's decision whether, and how, to retry."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency","__idx":2},"children":["Idempotency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every operation method takes a trailing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey: String?"]}," parameter. Pass a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["stable, caller-chosen"," ","key that's the same across retries of the same logical request"]},", and the API can recognize a retried"," ","request as a duplicate rather than double-processing it (e.g. double-authorizing, double-capturing)."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","data-title":"Java","header":{"title":"Java","controls":{"copy":{}}},"source":"String idempotencyKey = \"authorize-\" + orderId; // stable per logical attempt, reused on retry\n\ntry {\n    AuthorizeOutcome outcome = client.authorize(request, idempotencyKey);\n} catch (RatepayNetworkException e) {\n    // safe to retry with the SAME idempotencyKey\n    AuthorizeOutcome retried = client.authorize(request, idempotencyKey);\n}\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","data-title":"Kotlin","header":{"title":"Kotlin","controls":{"copy":{}}},"source":"val idempotencyKey = \"authorize-$orderId\" // stable per logical attempt, reused on retry\n\nval outcome = try {\n    client.authorize(request, idempotencyKey)\n} catch (e: RatepayNetworkException) {\n    // safe to retry with the SAME idempotencyKey\n    client.authorize(request, idempotencyKey)\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Passing null does not give you retry-safety"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," (or omit the parameter in Kotlin), the SDK auto-generates a key with its internal"," ","random generator, which returns a fresh random UUID ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["on every call"]},". It is not derived"," ","from the request body, so two calls with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," get two different keys, even with byte-for-byte identical"," ","bodies, and the API treats them as two separate requests. A retry without an explicit key is therefore"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," deduplicated, which is not what you want for retries. Always pass your own stable key when retrying."]}]}]},"headings":[{"value":"Idempotency and retries","id":"idempotency-and-retries","depth":1},{"value":"The SDK does not retry for you","id":"the-sdk-does-not-retry-for-you","depth":2},{"value":"Idempotency","id":"idempotency","depth":2}],"frontmatter":{"seo":{"title":"Idempotency and retries"}},"lastModified":"2026-08-17T10:04:52.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/developer/sdk/errors-and-resilience/idempotency-and-retries","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}