Idempotency

Networks fail halfway. An Idempotency-Key lets you retry a POST without creating, or paying for, the same thing twice.

How it works

Every POST accepts an Idempotency-Key header of up to 255 characters.

curl https://api.129.212.147.181.sslip.io/v1/documents \  -H "Authorization: Bearer $DOCGEN_API_KEY" \  -H "Docgen-Subject: wp_user:48213" \  -H "Idempotency-Key: 4f1c2a9e-lease-order-8812" \  -d '{ "session": "ses_01JBA2M8K3Q4R5S6T7V8W9X0YZ" }'

• The first request with a key does the work. We keep its response for 24 hours.
• A retry with the same key and the same body gets that original response back, status code included. Nothing runs again.
• For documents, a retry returns the original document, so a lost response never pays the model twice. The same holds for session messages: a retried turn isn't run again.
• Server errors (5xx) are not kept: retrying with the same key does the work again.

Choosing keys

Use something unique to the action in your system: a UUID you store with the order, or your own record ID. Make a new key for a new action; reuse it only to retry.

Conflicts

• Same key, different body: 409 idempotency_key_reused.
• Same key while the first request is still running: 409 idempotency_request_in_progress. Retry shortly.