Idempotency

Idempotency keys let you safely retry API requests without accidentally creating duplicate resources. This is essential for reliable integrations where network failures can leave you uncertain whether a request succeeded.

What is Idempotency?

An idempotent operation produces the same result whether it is executed once or multiple times. For API requests, this means that retrying a failed request with the same idempotency key will not create a duplicate resource — the API returns the original response instead.

This is critical for operations like creating deals or uploading documents where a network timeout might leave you unsure whether the server processed your request.

Idempotency-Key Header

Include the Idempotency-Key header with a unique identifier on any POST or PATCH request. We recommend using UUID v4 values.

Name	Type	Required	Description
Idempotency-Key	string	Optional	A unique identifier for this request. UUID v4 recommended. Maximum 255 characters.

Idempotency keys are scoped to your organization. Two different organizations can use the same key without conflict.

Key Expiration

Idempotency keys are stored for 24 hours from the time of the original request. After the TTL expires, the key is removed and the same key can be reused for a new request.

Do not rely on keys being available after 24 hours. If you need to retry a request after the TTL, generate a new idempotency key and verify the resource state first to avoid duplicates.

Safe Retry Patterns

Generate the idempotency key before making the request, then reuse the same key for all retry attempts:

# Generate a UUID v4 idempotency key
IDEM_KEY=$(uuidgen)

curl -X POST "https://api.banklyze.com/v1/deals" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Org-Id: $ORG_ID" \
  -H "Idempotency-Key: $IDEM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Trucking LLC",
    "entity_type": "llc"
  }'

# Retry with the SAME key — returns the cached response
curl -X POST "https://api.banklyze.com/v1/deals" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Org-Id: $ORG_ID" \
  -H "Idempotency-Key: $IDEM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Trucking LLC",
    "entity_type": "llc"
  }'

Replayed Responses

When the API returns a cached response for a previously-seen idempotency key, it includes the X-Idempotent-Replayed: true header. This lets your application distinguish between original and replayed responses.

Replayed response

HTTP/1.1 201 Created
X-Idempotent-Replayed: true
Content-Type: application/json

{
  "id": 42,
  "business_name": "Acme Trucking LLC",
  "status": "new",
  "created_at": "2025-01-15T10:30:00Z"
}

When to Use Idempotency Keys

Method	Idempotency Key	Reason
POST	Recommended	Creates new resources — retries could cause duplicates.
PATCH	Recommended	Partial updates may have side effects (e.g., triggering reprocessing).
PUT	Optional	Full replacement is naturally idempotent, but keys add safety.
GET	Not needed	Read operations are inherently idempotent.
DELETE	Not needed	Deleting an already-deleted resource returns 404 safely.

SDK Usage

The Python SDK automatically generates idempotency keys for POST and PATCH requests. You can optionally provide your own key:

Python SDK — automatic idempotency

from banklyze import BanklyzeClient

client = BanklyzeClient(api_key="sk_live_...", org_id=1)

# The SDK generates idempotency keys automatically for POST/PATCH
deal = client.deals.create(
    business_name="Acme Trucking LLC",
    entity_type="llc",
    idempotency_key="your-custom-key",  # optional override
)

Pagination

Changelog