Idempotency

When you record a decision, the network can fail after MeshQu has persisted it but before your code receives the response. Retrying blindly would create a duplicate decision. An idempotency key closes that gap: retry as many times as you like and you get back the same decision, recorded once.

Mental model: the idempotency key is a stable name for a business operation. The first request with that key records a decision; every later request with the same key returns the decision that already exists.

Evaluate vs Record — Idempotency applies to record, the endpoint that persists a decision. evaluate records no decision, so it has no decision to deduplicate. It is not a no-op write, though: resolving the active policies may append one row to the tenant’s append-only policy_snapshots table, returned as policy_snapshot_id. That append is content-addressed — a repeat call resolving to the same policies reuses the existing snapshot and appends nothing.

How it works

When you call POST /v1/decisions/record with an idempotency_key, MeshQu checks whether a decision already exists with that key for your tenant:

Outcome	Status	`is_new`	What happens
Key not seen before	`201 Created`	`true`	Policies are evaluated, a decision is recorded and returned.
Key already used, same content	`200 OK`	`false`	The original decision is returned immediately — no re-evaluation.
Key already used, different content	`409 Conflict`	—	Refused. Nothing is recorded, and the stored decision is not returned.

The second case returns the stored decision without running policies again, so retries are both safe and cheap.

A key is bound permanently to the first request recorded under it. Sending a different request under a key that is already in use is refused with 409 and the error code IDEMPOTENCY_KEY_REUSED — MeshQu will not hand you a receipt for content you did not submit, and will not silently record your request under someone else’s key.The 409 body tells you which of the two things to do:

{
  "error": {
    "code": "IDEMPOTENCY_KEY_REUSED",
    "message": "This idempotency_key is already bound to a different request for this tenant. The submitted request was NOT recorded, and the previously recorded decision was NOT returned.",
    "details": {
      "existing_decision_id": "…",
      "existing_recorded_at": "…",
      "submitted_request_fingerprint": "…",
      "recorded_request_fingerprint": "…",
      "fingerprint_covers": ["context.decision_type", "context.fields", "…"],
      "fingerprint_excludes": ["correlation_id", "…"],
      "fingerprint_ignores": ["evidence_manifest", "evidence_manifest_digest", "action", "options.chain"],
      "remedy": {
        "to_record_this_request": "Resubmit with a NEW idempotency_key. …",
        "to_replay_the_recorded_decision": "Resubmit the ORIGINAL request body unchanged under this key, …"
      }
    }
  }
}

Retrying the same mismatched pair will fail the same way — this is not a transient error.

What counts as “the same content”

The comparison is over the decision context: decision_type, fields, evidence, source_artifact, and metadata. Values the server writes into the context for you are excluded, so an ordinary network retry can never conflict:

metadata.correlation_id — regenerated per request when you send no X-Correlation-Id header.
The agent_licence_* metadata keys — resolved server-side from your API key, so a re-issued licence does not conflict.

Request inputs that live outside the context are not compared at all: evidence_manifest, evidence_manifest_digest, action and options.chain. Changing only one of those under an existing key returns the stored decision (200) rather than a 409. The 409 body publishes this list as fingerprint_ignores.

First request:  POST /record { idempotency_key: "payment-12345", …context A } → 201, is_new: true
Retry request:  POST /record { idempotency_key: "payment-12345", …context A } → 200, is_new: false
Reused key:     POST /record { idempotency_key: "payment-12345", …context B } → 409, IDEMPOTENCY_KEY_REUSED

Recording with an idempotency key

curl -X POST https://api.meshqu.com/v1/decisions/record \
  -H "Authorization: Bearer mqu_YOUR_API_KEY" \
  -H "X-MeshQu-Tenant-Id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "decision_type": "payment_approval",
      "fields": { "amount": 50000, "reference": "PAY-12345" }
    },
    "options": {
      "idempotency_key": "payment-12345-approval"
    }
  }'

import { MeshQuClient } from '@meshqu/client';

const meshqu = new MeshQuClient({
  baseUrl: 'https://api.meshqu.com',
  tenantId: process.env.MESHQU_TENANT_ID!,
  apiKey: process.env.MESHQU_API_KEY!,
});

const result = await meshqu.record(
  {
    decision_type: 'payment_approval',
    fields: { amount: 50000, reference: 'PAY-12345' },
  },
  { idempotency_key: 'payment-12345-approval' },
);

console.log(result.is_new); // true on first call, false on retries
console.log(result.decision.id);

The TypeScript SDK requires idempotency_key on record() and throws if it is missing or blank. The REST API treats it as optional but strongly recommended — a record call without a key still succeeds, it just won’t be deduplicated. For any workflow that can retry (which is most of them), always supply one.

Choosing good keys

A key should uniquely and deterministically identify the business operation, so that a retry of the same operation produces the same key. Good keys — derived from a stable business identifier:

payment-{payment_id}-approval
order-{order_id}-release
invoice-{invoice_id}-validation-v1

Bad keys — collide across operations, or change on every retry (defeating the purpose):

approval-1        # too generic — collides across transactions
user-123          # multiple operations per user
${Date.now()}     # different every call — never deduplicates
${random()}       # different on every retry — never deduplicates

Key format

Property	Value
Length	1–255 characters
Case sensitivity	Case-sensitive (`ABC` ≠ `abc`)
Scope	Unique per tenant — the same key may exist in different tenants

A key, once used, is bound to that decision permanently within the tenant. There is no expiry, so a retry months later still returns the original decision. If a decision genuinely needs to be re-made (for example after corrected input data), use a new key with a version suffix — this is enforced, not merely advised: reusing the old key with the corrected data is refused with 409.

invoice-123-validation-v1   # original
invoice-123-validation-v2   # after data correction — a new, distinct decision

Safe-retry pattern

Treat both 200 and 201 as success. Retry only on server errors (5xx) and network failures — never on client errors (4xx), which indicate a request that won’t succeed on retry. 409 IDEMPOTENCY_KEY_REUSED is one of those: it means the key is already bound to different content, so retrying unchanged will fail identically. Choose a new key, or restore the original request body.

import { MeshQuError } from '@meshqu/client';

async function recordWithRetry(
  context: DecisionContext,
  idempotencyKey: string,
  maxRetries = 3,
) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      // The SDK returns on both 200 (idempotent hit) and 201 (new record).
      return await meshqu.record(context, { idempotency_key: idempotencyKey });
    } catch (err) {
      // Don't retry client errors — they won't succeed on retry.
      if (err instanceof MeshQuError && err.status >= 400 && err.status < 500) {
        throw err;
      }
      if (attempt === maxRetries) throw err;

      // Exponential backoff: 200ms, 400ms, 800ms
      await new Promise((r) => setTimeout(r, 2 ** attempt * 100));
    }
  }
}

Because the key is stable, a retry after a post-write network failure returns the already-recorded decision instead of creating a second one.

Common patterns

Queue processing — use the message ID so reprocessing a redelivered message is a no-op:

async function handleMessage(message: QueueMessage) {
  await meshqu.record(message.context, {
    idempotency_key: `queue-${message.id}`,
  });
  await message.acknowledge(); // safe — a crash + reprocess yields the same decision
}

Inbound webhooks — key on the delivery ID of the upstream system so its retries are absorbed:

const idempotencyKey = `inbound-${req.headers['x-webhook-id']}`;
await meshqu.record(parseContext(req.body), { idempotency_key: idempotencyKey });

Environment prefixes — avoid cross-environment collisions if a non-production system can ever reach the same tenant:

const key = `${process.env.NODE_ENV}-payment-${paymentId}`;

Verifying a key was used

Recorded decisions carry their idempotency_key. List recent decisions and filter:

curl "https://api.meshqu.com/v1/decisions?limit=50" \
  -H "Authorization: Bearer mqu_YOUR_API_KEY" \
  -H "X-MeshQu-Tenant-Id: YOUR_TENANT_ID" \
  | jq '.items[] | select(.idempotency_key == "payment-12345-approval")'

Integration Patterns — where recording fits in your request flow.
Decision Chains — grouping related decisions into an ordered sequence.

Getting Started

Concepts

API Reference

SDK

Guides

Recipes

Security

Meta

How it works

What counts as “the same content”

Recording with an idempotency key

Choosing good keys

Key format

Safe-retry pattern

Common patterns

Verifying a key was used

​How it works

​What counts as “the same content”

​Recording with an idempotency key

​Choosing good keys

​Key format

​Safe-retry pattern

​Common patterns

​Verifying a key was used

​Related

How it works

What counts as “the same content”

Recording with an idempotency key

Choosing good keys

Key format

Safe-retry pattern

Common patterns

Verifying a key was used

Related