Core concepts

Idempotency

Retry Management API mutations without creating duplicate account operations.

Account and finance mutations require an Idempotency-Key header. Reuse the same key only when retrying the same logical operation.

Idempotency-Key: account-create-client-1042

Generate keys

Use a UUID or a stable identifier derived from your own operation record.

const idempotencyKey = crypto.randomUUID();

Keys must be non-empty and no longer than 100 characters. They are unique within your Koneth organization.

Retry safely

Create the key once
Store the key with the operation in your database before sending the request.
Send the request
Include the stored key in Idempotency-Key.
Retry with the same key
If the connection fails or the response is lost, retry the identical request with the original key.
Use a new key for a new action
Even if the new action targets the same account, give it a different key.

When Koneth finds an existing command for the key, it returns that command with duplicate: true instead of queuing another operation.

Request IDs

Mutation bodies also include a requestId. Use your internal operation or correlation ID. You may send the same value in X-Request-Id to correlate API billing and application logs.

Idempotency-Key: deposit-client-1042-20260825
X-Request-Id: funding-client-1042-20260825