From 9fcd38323ea97da67bde2e124522c76f4189ff61 Mon Sep 17 00:00:00 2001 From: PIERLUIGI VITI Date: Mon, 17 Aug 2026 15:58:20 +0200 Subject: [PATCH] docs(errors): hint for idempotency_key_reused The gateway now binds an Idempotency-Key to the request, so reusing a key with different terms is a 422 idempotency_key_reused instead of a 200 carrying the first payment (commercelayer/rail0-gateway#155). Adds the hint and says so where the README documents the key. Co-Authored-By: Claude Opus 5 --- README.md | 2 ++ lib/rail0/error_hints.rb | 1 + 2 files changed, 3 insertions(+) diff --git a/README.md b/README.md index aa0d3d0..7bb6ddf 100644 --- a/README.md +++ b/README.md @@ -228,6 +228,8 @@ the other three is the **holding's** id, not the token address. ```ruby client.payments.create(params, idempotency_key: nil) # or keyword fields +# Reusing a key for DIFFERENT terms raises Rail0::ApiError with code +# "idempotency_key_reused" (422) instead of returning the first payment. client.payments.get(id) client.payments.list(status: "authorized", disputed: false, chain_id: 84532, sort: "-created_at") client.payments.transactions(id, operation: "capture") diff --git a/lib/rail0/error_hints.rb b/lib/rail0/error_hints.rb index 0e11307..a84e879 100644 --- a/lib/rail0/error_hints.rb +++ b/lib/rail0/error_hints.rb @@ -46,6 +46,7 @@ module Rail0 "payment_already_exists" => "a payment with this id already exists on-chain", # Ported from rail0-go, which had drifted five codes ahead of this table (#13). "unsupported_payment_method" => "the payee (merchant) doesn't accept this token/chain — check the merchant's payment methods", + "idempotency_key_reused" => "that Idempotency-Key was already used for a payment with different terms — reuse it only to retry the same request, or pick a new key", "unknown_token" => "the token isn't configured on this chain", "no_active_contract" => "no active RAIL0 contract on that chain", "missing_param" => "a required parameter is missing from the request",