Idempotency-key vs reference

Add Idempotency-Key in the header of the request; the system will skip your request processing and return a success directly should you execute the same request twice

The feature is applied on endpoints which write to the database :

• Create transaction (also batch and numscript)

• Update metadata (account or transaction)

• Revert transaction

When requesting the service with a IK, if the IK has already been used on another request terminated with success (Status code 2XX), the same response will be returned, plus a header named "Idempotency-Hit" with the value "true".

Given a IK, if the request does not match the originated request, either if the path or the body does not match, the service will responds with a 400 status code.

A reference field can be added in the body of a transaction creation. if this reference already exists, an error will be returned.

OK, but which one should I use then ?

To help pick one vs the other. You can use a reference if you have a unique entity on your system against which the transaction should be matched uniquely (e.g. if you have a refund object in your system, and want to then create a unique ledger transaction for that refund); you’ll then get an error if you try to re-submit a tx with that same reference. If the identity of what you’re creating a ledger transaction for is less obvious, idempotency key header is otherwise a solid choice; the system will skip your request processing and return a success directly should you execute the same request twice.