Idempotency

Idempotency guarantees that a given API request is only processed once and the corresponding action is only executed once. This ensures that failures and retries do not result in duplicates. Any subsequent API request received with a previously used idempotency key will return a 409 - Conflict with error= idempotency_key_conflict.

The Numeral API supports idempotency through the optional addition of a unique ID in the Idempotency-Key HTTP header of your API calls:

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '

To note:

  • Idempotency are typically your internal database UUIDs
  • Idempotency keys are scoped by your organisation. They apply to all API keys and API requests
  • Idempotency is not applied across objects. This means the same idempotency key can be used for a payment order and counterparty account
  • GETAPI requests are idempotent by nature and do not require nor support idempotency keys