Idempotency

The Lightfield API supports idempotency keys on write operations, allowing you to safely retry requests without performing the same action twice. This is useful when network issues or timeouts leave you uncertain whether a request succeeded.

How it works

Include an Idempotency-Key header with a unique string value (up to 255 characters) on any POST 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 $API_KEY" \
  -H "Idempotency-Key: req-abc-123" \
  -d '{
        "fields": {
          "system_name": "Acme Corp"
        }
      }'

Idempotency keys are scoped to your organization and to the specific operation type. This means the same key value can be safely used across different entity types or operation types (create vs. update) without conflict.

Idempotency keys expire after 24 hours. After expiration, a request with the same key will be treated as a new request.

Supported operations

Operation	Method	Endpoint
Create an object	POST	/v1/{entityType}
Update an object	POST	/v1/{entityType}/{id}

Idempotency keys are not required on GET requests, which are inherently idempotent.

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

{
  "type": "idempotency_conflict",
  "message": "An operation with this idempotency key is already in progress. Please wait and retry."
}

Failed requests

If the original request failed, retrying with the same idempotency key will re-attempt the operation rather than returning the cached error. This means you can safely reuse the same key when retrying after a failure.

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

{
  "type": "bad_request",
  "message": "Idempotency key must be 255 characters or fewer."
}

Best practices

• Use UUIDs or unique request identifiers — Generate a UUID v4 or use your own internal request ID to ensure uniqueness.
• Retry with the same key — When retrying a failed or timed-out request, always reuse the original idempotency key. Using a new key could result in a duplicate operation.
• Scope keys to a single operation — While the API namespaces keys per entity type and operation, using globally unique keys avoids any confusion.
• Don’t reuse keys for different payloads — An idempotency key should always correspond to the same intended operation. Sending a different request body with a previously used key will return the original cached response, not process the new payload.