Idempotency

Networks fail. Queues redrive. Mobile clients retry. legesis exposes idempotency keys so you can safely call any state-mutating endpoint more than once without creating duplicate envelopes, files, or webhook subscriptions.

How it works

Pass an Idempotency-Key header on POST, PATCH, and DELETE requests:

curl -X POST https://app.legesis.com/api/v1/envelopes \
  -H "X-API-Key: $LEGESIS_API_KEY" \
  -H "Idempotency-Key: 7f3c2a8f-9e1d-4b56-9c2e-2cb1d7c3aaaa" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "...", "files": [...] }'

legesis stores the response associated with that key for 24 hours. If the same key arrives again with the same request body, the original response is replayed verbatim — same status code, same body, same Request-Id.

Recommended format

A fresh UUIDv4 per logical operation is the safe default:

const key = crypto.randomUUID();

Persist the key alongside whatever local state you have for the operation (database row, queue message). When you retry, reuse the same key.

What counts as the "same" request?

legesis hashes the request body. Same key + same body → cached replay. Same key + different body → 409 Conflict with the original response, so you notice the mismatch.

What's exempt?

• GET requests are naturally idempotent and don't need the header.
• The /health endpoint is unauthenticated and exempt.
• Webhook deliveries from legesis to your endpoint follow a different retry/backoff model (see retry logic).