Idempotency

​

How it works

1. First time with that key + tenant: process the request normally and cache the response keyed off (tenant_id, idempotency_key, body_hash) for 24 hours.
2. Same key + same body: return the cached response. The request is not processed again.
3. Same key + different body: return idempotency_conflict (HTTP 409) so you know the key was reused with mismatched intent.

​

Where to use it

• POST /api/v1/policies/
• POST /api/v1/yara-rules/
• POST /api/v1/yara-policies/
• POST /api/v1/sdp/policies/
• POST /api/v1/safety-policies/
• POST /api/v1/api-keys/
• POST /api/v1/tenants/
• POST /api/v1/billing/portal-session
• POST /api/v1/billing/create-checkout-session
• POST /api/v1/support/tickets

​

Generating a key

curl -X POST https://api.lasscyber.com/api/v1/policies/ \
  -H "Authorization: Bearer ak_live_…" \
  -H "Idempotency-Key: 6f1e3c00-2c5a-4c58-9b2c-2b6f7a4f3a9d" \
  -H "Content-Type: application/json" \
  -d '{ "name": "inbound-strict", "slug": "inbound-strict", ... }'

​

SDK helpers

​

Python

from agnes import Agnes
import uuid

agnes = Agnes()

agnes.policies.create(
    policy,
    idempotency_key=str(uuid.uuid4()),
)

​

TypeScript

import { Agnes } from "@lasscyber/agnes-security";

const agnes = new Agnes();

await agnes.policies.create(policy, {
  idempotencyKey: crypto.randomUUID(),
});

​

Conflicts

HTTP/1.1 409 Conflict

{
  "detail": "Idempotency-Key was reused with a different request body.",
  "code": "idempotency_conflict",
  "request_id": "...",
  "doc_url": "https://docs.lasscyber.com/errors/idempotency_conflict"
}

​

Cache lifetime

• 24 hours from the first request. After that the key is forgotten and a new request with the same key is treated as a fresh write.
• Cache entries are not visible across tenants.
• Cache entries survive Cloud Run autoscale events (the cache is Postgres-backed).

​

Common pitfalls

• Generating the key inside the retry loop. A fresh key per retry is a different request as far as Agnes is concerned. Generate the key once outside the retry loop.
• Using the same key for different operations. A key scopes to the full request body, so different operations naturally have different bodies — but using "create-policy-1" for both a policy create and a rule create is asking for confusion. Prefer UUIDs.
• Sending an empty key. The API ignores empty / whitespace-only values. To use idempotency, send a real value.

​

Next

• Errors → idempotency_conflict
• Rate limits — the other reason a retry might come back differently.