Idempotency
Retrying a request after a timeout should not run the work twice. Talonic supports this per endpoint: a client-supplied Idempotency-Key on POST /v1/extract, automatic deduplication on POST /v1/process, and dedicated keys on a few other POST endpoints. GET requests are naturally safe to retry.
Idempotency-Key on POST /v1/extract
Send a unique string (a UUID is recommended) of at most 64 characters in the Idempotency-Key header. A longer key is refused before any work with 400 (error: invalid_idempotency_key, code: VALIDATION_ERROR).
curl -X POST https://api.talonic.com/v1/extract \
-H "Authorization: Bearer $TALONIC_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "file=@invoice.pdf"| Situation | Behavior |
|---|---|
| Same key, first extraction finished | Returns 200 with the original result and cached: true. No new extraction runs. |
| Same key, first request still running | Not blocked: the duplicate runs as a new extraction. Wait for the first response before retrying. |
| Same key, different body | The key alone decides: the original result is replayed. Use a new key for a new document. |
| Key lifetime | Replays are guaranteed for 24 hours. No expiry is enforced today, so a key stays bound to its first result, but do not build on reuse past 24 hours: generate a fresh key per logical operation. |
Automatic deduplication on POST /v1/process
POST /v1/process needs no header: the server derives the key from your workspace, the stored configuration, the batch (if any) and a hash of the file. Re-submitting the same file to the same configuration within 24 hours returns the existing run; with a batch_id, the same file is never processed twice in that batch.
Other endpoints
App runs accept their own idempotency key (at most 64 characters), and delivery dispatch deduplicates on its own key; see the Apps API and Delivery API. Other write endpoints do not deduplicate, so check state with a GET before retrying them.