Idempotency

A network error can leave you unsure whether a request reached Narya. Send an Idempotency-Key header with each create, and a retry with the same key returns the first response instead of creating the record twice.

POST /integration/v1/companies
Idempotency-Key: 0192f6c4-8a20-7d31-b4c5-d6e7f8a9b0c1
Content-Type: application/json

{"name": "Kedai Ali Sdn Bhd", "external_ref": "HQ-C-1001"}

How it worksCopy Anchor Link

• Use a unique value per logical request, such as a UUID, up to 255 characters.
• Repeat a request within 24 hours, to the same path, with the same key and byte-for-byte the same body, and Narya returns the first response with Idempotent-Replayed: true.
• The same key with a different path or body returns 409, with Idempotency-Key named in invalid_params.
• A repeat sent while the first request is still running also returns 409. Retry it shortly.
• An Idempotency-Key only matches requests sent with the same integration key.
• Narya keeps every response except a 5xx, refusals included. A retry within 24 hours replays a 404 or 409 even after you fix the cause, so send a new key once you change anything.
• A retry after a 5xx runs the request again.

Which requests take itCopy Anchor Link

Every POST takes it:

• creating enterprises, companies, tradings, acquirers and trading enrollments
• registering devices, one at a time or in a batch
• decommissioning a device

PUT and DELETE do not need it, because repeating them leaves the same state.

Issuing an activation code is different. Narya does not keep the code, so a retry issues a new code that replaces the first one, even with the same Idempotency-Key.