Idempotency

Overview

Idempotency keys ensure that duplicate requests (e.g., from retries or network issues) do not create duplicate side effects. Send a unique key in the Idempotency-Key header for mutating requests; the API returns the same response for replays within the key's validity window.

Idempotency key header

Include Idempotency-Key: <unique_value> in the request headers. The value should be a UUID, random string, or other unique identifier generated by the client. Use the same key for retries of the same logical operation; use a new key for each distinct operation.

Authorization: Bearer $DMTR_API_KEY
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "position_id": "meg-2026-047",
  "type": "sell",
  "quantity": 5,
  "price_per_unit": 25000
}

Behavior on replay

When a request with a previously seen idempotency key arrives, the API returns the stored response from the original request (same status, body, headers). No duplicate side effects occur. The key is tied to the request method, path, and body; changing any of these with the same key may result in a conflict error.

Key expiration

Idempotency keys are stored for a limited time (e.g., 24 hours). After expiration, a new request with the same key is treated as a new operation. Plan retries within the expiration window; for long-delayed retries, use a new key and handle potential duplicates at the application level.

Which endpoints support idempotency

Create and update endpoints that perform mutating operations support idempotency: e.g., create position, create transfer intent, create webhook. Read-only endpoints (GET, list) do not require idempotency keys. Check endpoint documentation for explicit support.