Idempotent requests

Networks fail after the request left and before the response arrived. Without protection, a retry of POST /v1/checks creates and charges a second check for the same document. The Idempotency-Key header prevents that.

How it works

Send any string unique to this submission, up to 200 characters, on the create call:

curl -X POST https://api.silvertext.com/v1/checks \
  -H "Authorization: Bearer $SILVERTEXT_API_KEY" \
  -H "Idempotency-Key: order-8812-draft-3" \
  -H "Content-Type: application/json" \
  -d '{ "text": "…" }'

A later call from the same account with the same key answers 202 with the first check's id and the header Idempotent-Replayed: true. No second check starts; nothing is charged twice. The key is scoped to your account, so two customers of yours may use the same string without colliding as long as you namespace it (customer-42:doc-7:v3).

Choosing a key

• Derive it from your own identity of the work: the document id plus its version, or a hash of the content plus the options.
• Do not use a random UUID generated on each attempt; that defeats the purpose.
• Change the key when the document or the options change. A replay ignores the new body and returns the old check.

In a client

async function submit(doc: { id: string; version: number; text: string }) {
  return api('/v1/checks', {
    method: 'POST',
    headers: { 'Idempotency-Key': `${doc.id}:${doc.version}` },
    body: JSON.stringify({ text: doc.text, title: doc.id }),
    retry: { attempts: 3, backoffMs: 1000 },
  });
}

With the key in place, the retry loop in Rate limits and backoff can retry a create call on a 5xx or a dropped connection the same way it retries a read.