Idempotency-Key: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
[email protected] (talk | contribs)
add page
 
[email protected] (talk | contribs)
m better wording
Line 1: Line 1:
= Idempotency keys =
= Idempotency keys =


Barion supports idempotency keys on selected API v6 creation endpoints. An idempotency key lets you safely retry a request when you cannot tell whether the first request reached Barion, for example after a timeout, closed connection, or other network error.
Barion supports idempotency keys on selected API v6 <code>POST</code>, <code>PATCH</code> and <code>DELETE</code> endpoints. An idempotency key lets you safely retry a request when you cannot tell whether the first request reached Barion, for example after a timeout, closed connection, or other network error.


When you retry the same request with the same <code>Idempotency-Key</code> header, Barion returns the original completed response instead of creating another record. Use idempotency keys for every creation request that your integration might retry.
When you retry the same request with the same <code>Idempotency-Key</code> header, Barion returns the original completed response instead of creating another record. Use idempotency keys for every supported write request that your integration might retry.


== Supported endpoints ==
== Supported endpoints ==
Line 16: Line 16:
* [[PayoutMethod-Delete-v6|DELETE /v6/recipients/{recipientid}/payout-methods/{payoutmethodid}]] — Delete a payout method
* [[PayoutMethod-Delete-v6|DELETE /v6/recipients/{recipientid}/payout-methods/{payoutmethodid}]] — Delete a payout method


If you omit the header, Barion processes the request normally and does not store an idempotent result. Retrying a creation request without an idempotency key can create a duplicate recipient or payout method.
If you omit the header, Barion processes the request normally and does not store an idempotent result. Retrying a supported write request without an idempotency key can repeat the operation. For creation endpoints, this can create a duplicate recipient or payout method.


== Header reference ==
== Header reference ==
Line 29: Line 29:
| GUID
| GUID
| No
| No
| Unique key that identifies one logical creation request for safe retries.
| Unique key that identifies one logical write request for safe retries.
|}
|}


Generate a new GUID for each creation request. A UUID/GUID v4 value is recommended.
Generate a new GUID for each supported write request. A UUID/GUID v4 value is recommended.


Do not reuse an idempotency key for a different operation, even on a different endpoint. Do not include personal data, email addresses, API keys, or other sensitive values in the key.
Do not reuse an idempotency key for a different operation, even on a different endpoint. Do not include personal data, email addresses, API keys, or other sensitive values in the key.
Line 42: Line 42:
The stored result includes the HTTP status code, response headers, and response body. If the first request created a recipient or payout method and returned <code>201 Created</code>, a retry with the same key and request body returns the same <code>201 Created</code> response and the same created identifiers.
The stored result includes the HTTP status code, response headers, and response body. If the first request created a recipient or payout method and returned <code>201 Created</code>, a retry with the same key and request body returns the same <code>201 Created</code> response and the same created identifiers.


Idempotency records are retained for 10 minutes. Retry with the same key only within this window. After the record expires, the same key can be processed as a new request and can create a duplicate.
Idempotency records are retained for 10 minutes. Retry with the same key only within this window. After the record expires, Barion no longer guarantees idempotent replay for that key. If the same operation is sent again, it may be processed as a new request. For creation endpoints, this can create a duplicate.


== Request matching ==
== Request matching ==
Line 60: Line 60:
== Recommended retry flow ==
== Recommended retry flow ==


# Generate a new GUID before sending the creation request.
# Generate a new GUID before sending each supported write request.
# Store the GUID with your local operation, order, or job record.
# Store the GUID with your local operation, order, or job record.
# Send the request with the <code>Idempotency-Key</code> header.
# Send the request with the <code>Idempotency-Key</code> header.
Line 67: Line 67:
# Stop retrying when you receive a definitive response.
# Stop retrying when you receive a definitive response.


Do not retry an uncertain creation by sending the same body with a new key. That can create a duplicate if the original request already succeeded.
Do not retry an uncertain operation by sending the same request with a new key. For creation endpoints, that can create a duplicate if the original request already succeeded. That can create a duplicate if the original request already succeeded.


== Responses and errors ==
== Responses and errors ==
Line 78: Line 78:
| Header is missing
| Header is missing
| The request is processed without idempotency.
| The request is processed without idempotency.
| Add an idempotency key to creation requests you may retry.
| Add an idempotency key to supported write requests you may retry.
|-
|-
| Header value is not a GUID
| Header value is not a GUID
Line 98: Line 98:
| Same key is reused after the 10-minute retention window
| Same key is reused after the 10-minute retention window
| Treated as a new request
| Treated as a new request
| Reconcile existing data before sending another creation request.
| Reconcile existing data before sending another supported write request.
|}
|}


Line 109: Line 109:
=== Successful responses ===
=== Successful responses ===


For successful creation responses, store the returned recipient or payout method identifiers. Future retries with the same key and body within the retention window return the original response.
For successful responses to supported write requests, store the returned recipient or payout method identifiers. Future retries with the same key and body within the retention window return the original response.


=== Validation and other 4xx responses ===
=== Validation and other 4xx responses ===
Line 121: Line 121:
Treat <code>5xx</code> responses and dropped connections as indeterminate. The operation may or may not have completed. Retry the same key and body within the 10-minute retention window when possible.
Treat <code>5xx</code> responses and dropped connections as indeterminate. The operation may or may not have completed. Retry the same key and body within the 10-minute retention window when possible.


Do not immediately send a new creation request with a new key after a <code>5xx</code> or network failure. First retry with the original key, then reconcile by checking existing recipients or payout methods if you still cannot determine the outcome.
Do not immediately send a new modifying request with a new key after a <code>5xx</code> or network failure. First retry with the original key, then reconcile by checking existing recipients or payout methods if you still cannot determine the outcome.


== Best practices ==
== Best practices ==


* Use an idempotency key for every creation request.
* Use an idempotency key for every supported write request.
* Persist the key until the operation has a definitive result.
* Persist the key until the operation has a definitive result.
* Retry network failures with the same key and the same body.
* Retry network failures with the same key and the same body.
* Use exponential backoff for repeated retries.
* Use exponential backoff for repeated retries.
* Do not reuse a key with a changed request body during the 10-minute retention window.
* Do not reuse a key with a changed request body during the 10-minute retention window.
* Reconcile existing data before sending a new creation request after an uncertain failure.
* Reconcile existing data before sending a new modifying request after an uncertain failure.

Revision as of 16:41, 5 June 2026

Idempotency keys

Barion supports idempotency keys on selected API v6 POST, PATCH and DELETE endpoints. An idempotency key lets you safely retry a request when you cannot tell whether the first request reached Barion, for example after a timeout, closed connection, or other network error.

When you retry the same request with the same Idempotency-Key header, Barion returns the original completed response instead of creating another record. Use idempotency keys for every supported write request that your integration might retry.

Supported endpoints

Recipients

Payout methods

If you omit the header, Barion processes the request normally and does not store an idempotent result. Retrying a supported write request without an idempotency key can repeat the operation. For creation endpoints, this can create a duplicate recipient or payout method.

Header reference

Header Type Required Description
Idempotency-Key GUID No Unique key that identifies one logical write request for safe retries.

Generate a new GUID for each supported write request. A UUID/GUID v4 value is recommended.

Do not reuse an idempotency key for a different operation, even on a different endpoint. Do not include personal data, email addresses, API keys, or other sensitive values in the key.

How Barion handles idempotency

For a request with an Idempotency-Key, Barion stores the first completed HTTP response for the authenticated caller, HTTP method, endpoint path, idempotency key, and request body.

The stored result includes the HTTP status code, response headers, and response body. If the first request created a recipient or payout method and returned 201 Created, a retry with the same key and request body returns the same 201 Created response and the same created identifiers.

Idempotency records are retained for 10 minutes. Retry with the same key only within this window. After the record expires, Barion no longer guarantees idempotent replay for that key. If the same operation is sent again, it may be processed as a new request. For creation endpoints, this can create a duplicate.

Request matching

To replay an existing response, the retry must use:

  • the same authenticated caller,
  • the same HTTP method,
  • the same endpoint path,
  • the same Idempotency-Key GUID,
  • the same request body.

Barion compares the captured request body, not just the business meaning of the JSON. Send the exact same serialized body when retrying. Changing fields, values, field order, or JSON formatting can be treated as a different request.

A retry with the same key and a different request body fails during the 10-minute retention window.

Recommended retry flow

  1. Generate a new GUID before sending each supported write request.
  2. Store the GUID with your local operation, order, or job record.
  3. Send the request with the Idempotency-Key header.
  4. If you receive a network error or timeout before receiving a response, retry the same request with the same key and the same body.
  5. If Barion returns 409 Conflict because the original request is still processing, wait briefly and retry with the same key and body. Use exponential backoff for repeated retries.
  6. Stop retrying when you receive a definitive response.

Do not retry an uncertain operation by sending the same request with a new key. For creation endpoints, that can create a duplicate if the original request already succeeded. That can create a duplicate if the original request already succeeded.

Responses and errors

Situation Barion response What to do
Header is missing The request is processed without idempotency. Add an idempotency key to supported write requests you may retry.
Header value is not a GUID 400 Bad Request Generate a valid GUID and send the request again.
First request is still processing 409 Conflict Retry the same key and body after a short delay.
Same key is reused with a different body 422 Unprocessable Entity Retry with the original request body. A changed body is not accepted for the same key during the 10-minute retention window.
Same key and body are retried after the first request completed Original status code and body Handle the response as the result of the original request.
Same key is reused after the 10-minute retention window Treated as a new request Reconcile existing data before sending another supported write request.

Handling HTTP status codes

Network errors and timeouts

Network errors are the main reason to use idempotency keys. If your client times out or the connection closes before you receive a response, retry the same request with the same key and body. The retry either creates the resource if the original request did not reach Barion, returns the original response if it did, or returns 409 Conflict while the original request is still running.

Successful responses

For successful responses to supported write requests, store the returned recipient or payout method identifiers. Future retries with the same key and body within the retention window return the original response.

Validation and other 4xx responses

Treat 4xx responses as definitive unless the response specifically says the original request is still processing. Reusing the original key with a changed body returns 422 Unprocessable Entity during the 10-minute retention window.

Authentication and authorization failures can happen before an idempotent result is stored. Fix authentication or permission issues before retrying.

Server errors

Treat 5xx responses and dropped connections as indeterminate. The operation may or may not have completed. Retry the same key and body within the 10-minute retention window when possible.

Do not immediately send a new modifying request with a new key after a 5xx or network failure. First retry with the original key, then reconcile by checking existing recipients or payout methods if you still cannot determine the outcome.

Best practices

  • Use an idempotency key for every supported write request.
  • Persist the key until the operation has a definitive result.
  • Retry network failures with the same key and the same body.
  • Use exponential backoff for repeated retries.
  • Do not reuse a key with a changed request body during the 10-minute retention window.
  • Reconcile existing data before sending a new modifying request after an uncertain failure.