Idempotency

Safely retry write operations with idempotency keys to prevent duplicate creates.

Overview

For write operations (POST, PATCH), include an Idempotency-Key header to ensure safe retries. If a network failure occurs and you're unsure whether the request succeeded, resend it with the same key — the API guarantees the operation only executes once.

curl -X POST https://api.lend.works/v1/leads \
  -H "Authorization: Bearer lw_live_xxxx" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"businessName": "Acme Corp", "contactFirstName": "John"}'

How It Works

1. Include an Idempotency-Key header with a unique value (UUID recommended)
2. The API processes the request normally and caches the response
3. Subsequent requests with the same key return the cached response with an Idempotency-Key-Replay: true header
4. Keys are valid for 24 hours after first use
5. Keys are scoped to your organization — different orgs can use the same key independently

Only 2xx responses are cached. If the original request returned an error, the retry will re-execute the operation.

Key Format

Keys must be 1-256 characters using only alphanumeric characters, hyphens, and underscores:

# Valid keys
550e8400-e29b-41d4-a716-446655440000
create_lead_batch_42
retry_2025_01_15_001

# Invalid keys (will return 422)
key with spaces
key/with/slashes

Response Headers

Behavior by Method

Error Codes

Concurrent Request Protection

When a request with an idempotency key is in-flight, subsequent requests with the same key receive a 409 Conflict response. This prevents race conditions where two identical requests execute simultaneously. The lock lasts 60 seconds.

SDK Support

The TypeScript SDK supports idempotency keys via the options parameter:

import { LendWorksClient } from '@lendworks/sdk-node'

const client = new LendWorksClient({ apiKey: 'lw_live_xxxx' })

// Pass an idempotency key for safe retries
const { data: lead } = await client.leads.create(
  {
    businessName: 'Acme Corp',
    contactFirstName: 'Jane',
    email: 'jane@acme.com',
  },
  { idempotencyKey: crypto.randomUUID() }
)

Best Practices

• Use UUIDs as idempotency keys for guaranteed uniqueness
• Generate a new key for each logically distinct operation
• Store the key alongside your request for debugging and audit trails
• Retry with the same key on network timeouts or 5xx errors
• Never reuse keys across different endpoints or request bodies
• Include keys on all writes — even if you don't plan to retry, it protects against accidental double-submits