Understanding Idempotency Key Validation Errors in the Formance API

When using idempotency keys with the Formance API for transactions, you may encounter validation errors if the transaction details change between retry attempts with the same idempotency key.

How Idempotency Keys Work

Idempotency keys ensure that the same transaction isn't processed multiple times. When you make a request with an idempotency key:

• If it's the first time using that key, the transaction will be processed normally

• If the key was used before with identical transaction details, the API will return the result of the original transaction

• If the key was used before but with different transaction details, the API will return a validation error

📄 Idempotency-key vs reference

Common Validation Error

Starting ledger v2.2, you will receive an error with code VALIDATION mentioning "invalid idempotency hash", when you're trying to reuse an idempotency key with different transaction parameters than the original request.

				"errorMessage": "invalid idempotency hash when using idempotency key '9B2NSuk....', has computed '3mzVSL5jx...' but 'hPSOvFiie...' is stored",
				"name": "V2ErrorResponse",
				"errorCode": "VALIDATION",
				"type": "V2ErrorResponse",
				"message": "API error occurred"

Best Practices

• Use unique idempotency keys for each distinct transaction

• Ensure all transaction details (including metadata) remain consistent when retrying with the same idempotency key

• If transaction details need to change, use a new idempotency key