Preventing duplicate writes during Netlify Function retries

Direct answer

The most reliable method is to keep an external idempotency table and use an atomic conditional write before every mutating call. Generate a unique key for the request, attempt to insert it into a datastore outside the function, and only proceed with the downstream write if the insert succeeds. If the key already exists, return the stored result and skip the write. Because Netlify Functions are stateless, this deduplication state cannot live in the function itself.

Confirmed behavior and likely explanation

Confirmed: Netlify Functions do not retain state between executions, may retry an invocation after a timeout, and offer no native idempotency key for outgoing HTTP requests. If a timeout occurs after the downstream service has already processed the request, the retry re-executes the function body and can create a duplicate record.

Likely: the original request reached the downstream service, but the response never arrived before the function deadline. Without an external record of that first attempt, the retry appears to the application as a brand-new request.

Steps for this case

1. Create or validate an idempotency key server-side. Use a UUID for system-triggered events. For client-triggered events, accept a client-supplied key only after validating its format and length; never use an unvalidated client value as a database key.
2. Reserve the key in an external table with an atomic conditional insert:
   • PostgreSQL: INSERT INTO idempotency_records (key, status, result) VALUES ($1, 'processing', NULL) ON CONFLICT (key) DO NOTHING. A row count of zero means a prior attempt exists.
   • DynamoDB: PutItem with ConditionExpression = attribute_not_exists(pk). A conditional check failure means a prior attempt exists.
3. If the reservation succeeded, call the downstream service. On success, update the record with the response and mark it completed. On failure, mark it failed or remove it according to your retry policy so a later attempt is not permanently blocked.
4. If the reservation failed because the key exists, read the stored result and return it immediately. Do not call the downstream service again.
5. Add a TTL or periodic cleanup for idempotency records so the table does not grow without bound.

One missing diagnostic detail

Does the downstream API support an Idempotency-Key header? If it does, forward the same key to the downstream service and treat local deduplication as a secondary guard. If it does not, the external table is your only reliable deduplication point.

Verification

Deploy a test function that writes to PostgreSQL or DynamoDB using the conditional insert above. Force a timeout by delaying the downstream response beyond the function limit, trigger the retry, and confirm that only one downstream record and one idempotency row exist. Check the function logs to ensure the second invocation returns the stored result instead of re-executing the write.

Assumptions

This guidance assumes standard Netlify Function timeout limits, an external datastore reachable within that timeout, and downstream writes that are not already idempotent. If the downstream service handles deduplication natively, coordinating keys between both layers requires additional testing.