Idempotency

Overview

The Prolifi API supports idempotency for all mutating requests (POST, PATCH, PUT, DELETE). By including an Idempotency-Key header, you ensure that the same operation is not executed more than once, even if you retry the request due to a network failure or timeout.

How it works

1. Include an Idempotency-Key header with a unique value (up to 255 characters).
2. Prolifi processes the request normally and caches the response.
3. If you send the same Idempotency-Key again, Prolifi returns the cached response instead of re-executing the operation.
4. Cached responses include an Idempotent-Replayed: true header so you know the response is a replay.

Request example

$
curl -X POST "https://api.prolifi.co/api/v1/public/customers" \
>
  -H "Authorization: Bearer sk_test_..." \
>
  -H "Idempotency-Key: create-customer-user123-attempt1" \
>
  -H "Content-Type: application/json" \
>
  -d '{"email": "john@example.com", "name": "John Doe"}'

If the request times out and you retry with the same Idempotency-Key, you will either receive the original response (if it was processed) or the request will be executed for the first time.

Key guidelines

Generating idempotency keys

Use a deterministic key derived from the operation being performed. Good strategies:

• UUID v4 for one-off operations: Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
• Action-based for business operations: Idempotency-Key: create-sub-cust123-plan456
• Hash-based for event reporting: Idempotency-Key: sha256(customer_id + event_name + timestamp)

Avoid reusing idempotency keys across different operations, as this will return the cached response from the first operation.

Replayed responses

When Prolifi returns a cached response, the Idempotent-Replayed header is set:

HTTP/1.1 201 Created
Idempotent-Replayed: true
Content-Type: application/json
{"data": {"id": "...", ...}}

Your application can check for this header to distinguish between first-time and replayed responses, though in most cases the distinction is not important.