Skip to content
Signkoi
Developer docs

Idempotency

Safely retry POST requests with the Idempotency-Key header without sending an envelope twice.

On this page

Networks fail. If a request to create or send an envelope times out, you can’t tell whether it went through. Send an Idempotency-Key header with every POST request and you can simply retry: Signkoi performs the action once and returns the same response to every retry.

How it works

  1. Generate a unique key for each operation — a UUID v4 is ideal — and send it in the Idempotency-Key header.
  2. Signkoi stores the first response (success or 4xx error) for 24 hours.
  3. A retry with the same key and the same request returns that stored response with the header Idempotent-Replayed: true, without doing anything again.

Example

curl -X POST https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/send \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Idempotency-Key: 5f1d7c1e-0b8a-4c2e-9f3d-61a2b7e4c905"

Retrying the same request with the same key returns the original response:

Replayed response
HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replayed: true
X-Request-Id: 7d0e1c2b-5f4a-4b3e-8d9c-0a1b2c3d4e5f

Rules

Idempotency rules
SituationResult
Same key, same method, path and body (including files) within 24 hoursThe stored response is replayed with Idempotent-Replayed: true.
Same key, different request422 idempotency_key_reused — use a new key for a new operation.
Retry while the first request is still running409 idempotency_in_progress — wait a moment and retry.
The first request failed with a 5xx errorNothing is stored, so a retry with the same key runs the request again.
Key empty or longer than 255 characters422 invalid_idempotency_key
GET, PUT, PATCH and DELETEThe header is ignored; these requests are naturally safe to repeat.
After 24 hoursThe key can be used again for a new request.

Keys are per account

Keys are scoped to your account, not to one API key, so two integrations of the same account should not share key values.