Idempotency

If a request times out or the connection drops, you often cannot tell whether the server processed it. Sending the same request again with an Idempotency-Key makes the retry safe: the server replays the stored response instead of running a second extraction.

Send a unique key in the Idempotency-Key header:

curl https://api.trusttyped.com/v1/extract \
  -H "Authorization: Bearer tt_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d9c1f60-2b1a-4d2e-9c88-3f0a1b2c3d4e" \
  -d '{ "schema": {"total": "number"}, "input": {"text": "Total 33000."} }'

Rules

• The key must be 1–255 printable ASCII characters (0x21–0x7E); a UUID is a good choice. Anything else returns 400 invalid_request with param: "Idempotency-Key".
• Replaying the same key with the same body within 24 hours returns the stored response, with the header Idempotent-Replayed: true. The replay does not run the engine again and does not count against concurrency.
• The stored request_id inside the body is the original one; the X-Request-Id response header is the id of the current request.
• The key cannot be combined with "stream": true → 400 idempotency_not_supported_for_stream.

Conflict responses (409)

code	When	Action
idempotency_key_reused	The key was already used with a different body (or the stored result can no longer be decrypted).	Use a new key for a genuinely new request, or resend the original body.
idempotency_in_progress	A request with this key is still being processed.	Wait and retry; the response includes Retry-After: 2.

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_in_progress",
    "message": "Request dengan Idempotency-Key ini sedang diproses.",
    "param": "Idempotency-Key",
    "request_id": "req_01J…",
    "doc_url": "https://docs.trusttyped.com/errors#idempotency_in_progress"
  }
}

What is stored, and for how long

Only results with a deterministic outcome (success and 4xx validation errors) are stored — transient failures (5xx, timeout, 429) are not, so a retry is processed again.

Stored responses are encrypted and kept at most 24 hours. The server cannot read them without your Idempotency-Key; when the key is absent or the server secret is rotated, the record is unreadable and is treated as a conflict. This keeps the service's zero-data-retention guarantee: no request body or result is otherwise stored or logged.

Best practice

Generate the key once per logical request — e.g. a UUID created before the first attempt — and reuse that same value for every retry of that request.