Idempotency

​

Sending an idempotency key

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_SAIL_API_KEY",
    base_url="https://api.sailresearch.com/v1",
)

response = client.responses.create(
    model="zai-org/GLM-5.2-FP8",
    input="Summarize this document.",
    extra_headers={"Idempotency-Key": "order-9f8e7d6c"},
)

curl -X POST https://api.sailresearch.com/v1/responses \
  -H "Authorization: Bearer YOUR_SAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-9f8e7d6c" \
  -d '{
    "model": "zai-org/GLM-5.2-FP8",
    "input": "Summarize this document."
  }'

​

Behavior

• Scope. Reservations are keyed by (organization, API key, idempotency key). The same key sent under a different API key is a distinct reservation. Rotating keys does not break replay, but sharing an idempotency key across keys won’t dedupe.
• Body fingerprint. Sail fingerprints the request body with SHA-256. Reusing a key with a materially different body returns 400 idempotency_error rather than replaying the earlier response. This prevents a retry from silently returning the wrong answer if the client changed the request.
• Retention. Customer-provided idempotency keys are retained for 24 hours. After that window, reusing the same key may be treated as a new logical request.
• Validation failures don’t consume the key. A request that fails validation (any 4xx before the reservation is written) does not reserve the key. You may retry with a corrected body using the same key.
• Replays reflect current state. A replay reads the current state of the underlying response record, not a frozen snapshot. For background requests, the returned status reflects the task’s most recent transition (e.g. queued → in_progress → completed).

​

Retrying with an idempotency key

​

When to retry

​

How to retry

import random
import time
import uuid
import requests

API_KEY = "YOUR_SAIL_API_KEY"
BASE_URL = "https://api.sailresearch.com/v1"

# One key, reused across every retry.
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4()),
}
body = {"model": "zai-org/GLM-5.2-FP8", "input": "Summarize this document."}

for attempt in range(5):
    try:
        resp = requests.post(f"{BASE_URL}/responses", headers=headers, json=body, timeout=30)
        resp.raise_for_status()
        break
    except requests.RequestException:
        # Network error or 5xx. Safe to retry, the key dedupes server-side.
        time.sleep(random.uniform(0, 2**attempt))
else:
    raise RuntimeError("all retries exhausted")

print(resp.json()["id"])

​

See also

• Sending Requests at Scale: batch and background patterns where idempotent retries are most useful.
• Webhooks: pair idempotent retries with webhook delivery so clients can re-drive submission without re-running inference.