How to make calls safely to avoid unintentional retries
Idempotency
As some of the operations with payouts involve not-reversible money flows, this API supports idempotency keys to prevent the same operation from being accidentally executed twice. This may happen when a request sent by the API client fails due to connection errors or other unexpected conditions. Using the same idempotency key, the API client can safely retry the operation knowing that Devengo will guarantee the operation associated with the key is executed only once.
How it works
To perform an idempotent request, provide an additional X-Devengo-Idempotency-Key header to the request. When an idempotency key is provided Devengo will save the status code and body of the first request made for that key. Subsequent requests with the same key will return the same status code and body. This approach will be applied regardless of whether the first request succeeded or failed.
What to use as the key
An idempotency key is a unique value generated by the client that the server uses to recognize subsequent retries of the same request. Defining the nature and implementing the uniqueness of the keys is up to the client. Still, Devengo suggests using V4 UUIDs or another random string with enough entropy to avoid collisions, like some client business identifier.
Duration and use of the keys
Devengo will store idempotency keys only for 7 days. After that period, the key will be removed from the system, and a new request will be generated if the old key is reused. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.
All POST 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.