Skip to main content
Network failures and timeouts are unavoidable. When a request to create a transaction or account times out, you cannot know whether the server processed it before the connection dropped. Without a mechanism to safely retry, you risk creating duplicate payments or records. Thiqwave supports idempotency keys to solve this problem. When you include an Idempotency-Key header on a supported request, Thiqwave stores the result of that request and returns the same response for any subsequent request made with the same key — without executing the operation a second time.

​
How to Use Idempotency Keys

Add the Idempotency-Key header to your request with a unique string value. A UUID v4 is the recommended format. 
curl -X POST https://api.thiqwave.com/v1/transactions \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -d '{
    "amount": 5000,
    "currency": "SAR",
    "recipient_account_id": "acct_01hx9z3k2p",
    "reference": "INV-2026-0042"
  }'

​
Supported Endpoints

The following endpoints support idempotency keys:
EndpointDescription
POST /v1/transactionsInitiate a payment or transfer
POST /v1/accountsCreate a new business account
POST /v1/compliance/kybSubmit a KYB verification request
Idempotency keys have no effect on GET, PATCH, or DELETE requests — those operations are either read-only or naturally safe to repeat.

​
How It Works

When you send a request with an Idempotency-Key:
  1. Thiqwave checks whether a request with that key has already been processed.
  2. If no prior request exists with that key, the request is executed normally and the result is stored against the key.
  3. If a matching request already exists, Thiqwave returns the stored response immediately — the operation is not executed again.
Stored results are retained for 24 hours from the time of the original request. After that, the key expires and can be reused (though reusing keys is not recommended).

​
Conflict Response

If you send the same Idempotency-Key with a different request body, Thiqwave returns a 409 Conflict error: 
{
  "error": "Conflict",
  "message": "An idempotency key conflict was detected. The provided key was previously used with a different request body.",
  "code": "IDEMPOTENCY_CONFLICT"
}
This protects you from accidentally overwriting the result of a previous operation. If you receive a 409 due to a key conflict, generate a new key and resubmit only if you intend to create a new, separate operation.

​
Best Practices

  • Generate one key per operation, not per session. Each distinct operation (e.g. each payment) should have its own unique key. Do not reuse a key for a second, unrelated request.
  • Use UUID v4. It is statistically unique, widely supported, and trivial to generate in any language.
  • Store the key alongside your operation record. Before sending a request, persist the idempotency key to your database. This allows you to retry with the exact same key if the request times out, and to correlate the result with your internal records.
  • Do not retry on 4xx errors other than 429. If a request fails with a validation error (422), fix the payload and generate a new idempotency key — retrying with the original key and a corrected payload will result in a 409 Conflict.