Idempotency

The API offers idempotency support to safely repeat requests without accidentally executing the same operation twice. This is useful when an API call is interrupted in transit and you do not receive a response. For example, if a request to create a charge does not respond due to a network connection error, you can retry the request with the same idempotency key to ensure that no more than one charge is created.

To make an idempotent request, provide an additional X-Idempotency-Key: <key> header to the request.

Example Request:

curl -i \
-H "Authorization: Bearer $KOBANA_TOKEN" \
-d '{"bank_billet":{"amount":12.34, "expire_at": "2021-11-15", "description": "Prestação de Serviço", "customer_person_name": "Nome do Cliente", "customer_cnpj_cpf": "125.812.717-28", "customer_zipcode": "12312123", "customer_address": "Rua quinhentos", "customer_city_name": "Rio de Janeiro", "customer_state": "RJ", "customer_neighborhood": "bairro"}}' \
-H 'Content-Type: application/json' \
-H 'X-Idempotency-Key: 4wE7HVG5rW3R7Xg1' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://api-sandbox.kobana.com.br/v1/bank_billets'

Kobana's idempotency works by saving the resulting status code and body of the first request made for any idempotency key, regardless of whether it was successful or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client that the server uses to recognize subsequent attempts of the same request. How you create unique keys is up to you, but we suggest using UUIDs V4 or another random string with sufficient entropy to avoid collisions.

Idempotency keys can be up to 255 characters.

Keys are eligible for automatic removal from the system after having at least 24 hours of use, and a new request will be generated if a key is reused after the original is removed. The idempotency layer compares the input parameters with those of the original request and errors, unless they are the same to prevent accidental misuse.

Results are only saved if an API endpoint has started executing. If input parameters fail validation or the request conflicts with another that was running simultaneously, no idempotent result will be saved because no API endpoint has started executing. It is safe to retry these requests.

All POST, PUT and PATCH requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.