Idempotency

Reuse an Idempotency-Key when retrying a supported write after a timeout. The API returns the first successful response instead of repeating the operation.

How it works

Include an Idempotency-Key header with a unique string value (up to 255 characters) on a supported write request. If the API receives a second request with the same key, it returns the cached response from the original request instead of re-executing the operation.

curl https://api.lightfield.app/v1/accounts \
  -H "Content-Type: application/json" \
  -H "Lightfield-Version: 2026-03-01" \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Idempotency-Key: req-abc-123" \
  -d '{
        "fields": {
          "$name": "Acme Corp"
        }
      }'

Idempotency keys are scoped to your organization and operation type. You can reuse a key value across different entity types or operations (create vs. update) without conflict.

Idempotency records have a default retention of 24 hours and are removed by a cleanup job. After removal, the same key can execute a new request. Don’t rely on a key expiring at an exact time; use a new key for a new operation.

Examples of supported operations

Operation	Method	Endpoint
Create an account	POST	/v1/accounts
Update an account	POST	/v1/accounts/{id}
Create a custom object record	POST	/v1/objects/{entitySlug}/values
Send an email*	POST	/v1/emails/send
Create an email draft*	POST	/v1/emails/draft

Merge requests also accept an idempotency key; follow that guide for merge retries.

Idempotency keys are not required on GET requests, which are inherently idempotent. Do not assume every POST supports them: starting a sequence test does not read Idempotency-Key, and retrying starts another test. Check the operation’s API reference before retrying a write.

*Remote email providers do not natively support Lightfield idempotency keys, so retry protection for these operations is best effort on Lightfield’s side.

Error handling

Concurrent requests with the same key

If you send two requests with the same idempotency key while the first is still processing, the second request will receive an HTTP 409 Conflict response:

HTTP/1.1 409 Conflict

{
  "error": {
    "type": "conflict",
    "message": "An operation with the same Idempotency-Key is already in progress. Please retry shortly."
  }
}

Failed requests

If the original request failed, retry with the same idempotency key. The API attempts the operation again rather than returning the cached error.

Invalid keys

Idempotency keys must be 255 characters or fewer. Requests with a longer key will receive an HTTP 400 Bad Request response:

HTTP/1.1 400 Bad Request

{
  "error": {
    "type": "bad_request",
    "message": "Idempotency-Key must not exceed 255 characters.",
    "code": "idempotency_key_too_long",
    "param": "Idempotency-Key"
  }
}

Best practices

• Generate a UUID v4 or use your own unique request ID.
• Reuse the original key when retrying a failed or timed-out request. A new key could create a duplicate operation.
• Use a globally unique key for each intended operation, even though the API namespaces keys by entity type and operation.
• Keep the request body unchanged when reusing a key. A different body with a previously used key returns the original cached response; it does not process the new payload.