Idempotency & Rate Limits

Idempotency

Money-moving endpoints require an Idempotency-Key header (UUID recommended).

curl -X POST "$BASE_URL/v1/transactions" \
  -H "X-API-Key: $THIQWAVE_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "quote_id": "'"$QUOTE_ID"'", "beneficiary_id": "'"$BENEFICIARY_ID"'" }'

Rule	Behaviour
Same key + same payload	Returns the original response — no duplicate created
Same key + different payload	409 IDM_0001
Missing key on money-moving POST	400 IDM_0002

Required on

Method	Path
POST	/v1/transactions
POST	/v1/payments

Quote-accept endpoints are idempotent at the business level — safe to retry.

Replay safely

Store the Idempotency-Key alongside the operation in your DB before the first attempt. On timeout/network error, retry the exact same call with the same key.

Rate limits

Enforced at the API gateway per API key.

Window	Limit
Per minute	100
Per hour	5,000

On 429, honour Retry-After (seconds). Enterprise plans have custom limits — contact support@thiqwave.com.

Correlation IDs

Send X-Request-ID: <uuid> on every request. It is echoed as correlation_id in any error and is the fastest path through support.