Idempotency-Key: Difference between revisions
add page |
m better wording |
||
| Line 1: | Line 1: | ||
= Idempotency keys = | = Idempotency keys = | ||
Barion supports idempotency keys on selected API v6 | 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 | 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 | 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 | | Unique key that identifies one logical write request for safe retries. | ||
|} | |} | ||
Generate a new GUID for each | 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 | 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 | # 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 | 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 | | 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 | | Reconcile existing data before sending another supported write request. | ||
|} | |} | ||
| Line 109: | Line 109: | ||
=== Successful responses === | === Successful responses === | ||
For successful | 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 | 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 | * 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 | * 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
- POST /v6/recipients — Create a new recipient
- PATCH /v6/recipients/{recipientid} — Update a recipient's name
- DELETE /v6/recipients/{recipientid} — Delete a recipient
Payout methods
- POST /v6/recipients/{recipientid}/payout-methods — Add a payout method to a recipient
- 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 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-KeyGUID, - 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
- Generate a new GUID before sending each supported write request.
- Store the GUID with your local operation, order, or job record.
- Send the request with the
Idempotency-Keyheader. - If you receive a network error or timeout before receiving a response, retry the same request with the same key and the same body.
- If Barion returns
409 Conflictbecause the original request is still processing, wait briefly and retry with the same key and body. Use exponential backoff for repeated retries. - 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.