Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Idempotency

Network requests fail. Clients retry. Without a deduplication contract, a retried POST quietly creates two records. The Scripe API gives every write endpoint a single contract for safe retries: pass an Idempotency-Key header. The server records the response under that key for 24 hours and replays it verbatim on subsequent requests with the same body — including the original status code.

​
How to use it

Generate a unique key per logical operation (a UUID is the obvious default — anything 1–64 chars matching [A-Za-z0-9_-] works) and send it on every retry of that operation: 
KEY=$(uuidgen)

curl -i https://api.scripe.io/v1/notes \
  -X POST \
  -H "Authorization: Bearer scripe_sk_live_…" \
  -H "Scripe-Api-Version: 2026-08-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{ "projectId": "proj_…", "content": "Hi" }'
The first request runs the handler. The response includes: 
HTTP/1.1 200 OK
Idempotent-Replayed: false
Within the next 24h, the same key + same body returns the cached response: 
HTTP/1.1 200 OK
Idempotent-Replayed: true
Your application logic does NOT need to special-case the replay path — the body is the original 200 envelope.

​
Validation rules

  • Key shape: 1–64 chars, regex ^[A-Za-z0-9_-]{1,64}$. Anything longer or with disallowed characters is silently ignored (treated as if no header was sent).
  • Scope: keys are scoped to (workspaceId, route). The same value can be reused safely across different endpoints.
  • Body hashing: we hash the canonicalised JSON body of the request (object keys sorted, no non-significant whitespace) with SHA-256. The hash, NOT the body itself, is what we compare on replay.
  • Window: 24 hours from the first request. After expiry the key can be reused with any body.

​
Conflict (409 idempotency_key_conflict)

If you send the same Idempotency-Key with a different body inside the 24h window, the server rejects the request: 
HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_conflict",
    "message": "Idempotency-Key was already used for a different request body in the last 24h.",
    "request_id": "req_…",
    "docs_url": "https://docs.scripe.io/api/v1/errors/idempotency_key_conflict"
  }
}
Practical fix: generate a fresh key when you mean a fresh operation. Reuse a key only when retrying a literal retry of an unchanged body.

​
Body size cap

Buffering the request body for hashing has an upper bound (256 KB by default; some endpoints set their own limit). Bodies larger than the cap return 413 payload_too_large even when an Idempotency-Key is sent. The cap on each endpoint matches its content cap, so this only fires on truly oversize inputs.

​
What’s NOT idempotent

  • GET endpoints. They’re read-only — Idempotency-Key on a GET is ignored.
  • Side effects you trigger via webhooks fired by the API (the webhook delivery itself has its own idempotency layer: receivers should dedupe on event.id).
  • Background jobs queued by POST /v1/posts/generations (coming in a later release) — those expose their own job-id-based idempotency.

​
When to use it (always, but here’s the threshold)

Whenever the cost of a duplicate write is non-zero. Notes and posts both fall into that category — a duplicate post in the customer’s queue is annoying. We strongly recommend including an Idempotency-Key on every write request as a default.