Idempotency-Key
Idempotency-Key
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 random GUID for each logical write request. A UUID/GUID v4 value is recommended.
Do not derive the GUID from personal data, API keys, or other sensitive values.
How Barion handles idempotency
For a request with an Idempotency-Key, Barion stores the first completed successful HTTP response for the authenticated caller, HTTP method, endpoint path, idempotency key, and request body.
Only 2xx responses are stored for idempotent replay. Server errors, such as HTTP 500, are not stored and are not replayed for later retries.
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.
Barion does not store or replay HTTP 5xx responses as idempotent results. If you receive a 5xx status code, 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.