Error Handling
Part of Workflow data synchronisation
Resolving conflicting updates from two systems
Identify competing record edits, choose a field-level rule and apply the resolution without overwriting another change.
When both systems change a shared value before either receives the other's edit, compare each change against the last confirmed common value. Apply the field's authority rule. Keep both proposed values until the decision is recorded; the last event to arrive is not necessarily the business decision that should prevail.
Key Facts on Data Sync Conflicts
- Last event not always correct
- The last arriving update does not necessarily represent the business decision.
- Need common baseline
- Without a trustworthy common value, do not infer correctness from timestamp alone.
- HTTP If-Match support
- Use standard mechanism to prevent silent overwrites in APIs that support it.
Establish whether edits compete
Suppose a sales agent changes a customer's contact preference from email to phone, while a service agent changes it from email to none. If email was the last confirmed common value, both sides changed the same field. If only one side changed, apply the permitted direction rule instead.
Keep the common value, each system's current value and available version, and the record pair. Record the actor or process when the applications expose it. If no trustworthy common baseline exists, do not infer that one current value is correct from its timestamp alone; hold the difference for an authority decision.
Choose a rule for the field
| Rule | Fits when | Limitation |
|---|---|---|
| Named authority | One application owns the fact | A valid correction made elsewhere needs its own route |
| Manual review | Meaning or consequences require a person | The field remains unresolved until someone decides |
| Merge separate fields | Each side owns different properties | A whole-record write can still overwrite another property |
| Time-based choice | Timestamps are comparable and recency is the intended rule | Clock differences and delayed delivery can mislead |
For a contact preference, manual review may be appropriate if either edit affects communication. For a service status owned by the service application, that authority can settle the value. Define the rule per field rather than relying on one whole-record default.
Where a product's field mappings determine which data syncs, in which direction, and how conflicts are handled, those mappings describe the product's behaviour rather than your business rule. Mappings and writable fields vary by connected app — some fields can only be mapped one way, and API limitations or read-only fields in the connected app may prevent the product from modifying them — so check the intended connection before treating a product default as the business rule.
Apply the resolution safely
Read the destination's current version before writing. Where its API supports a suitable conditional update, send the version with the write so an intervening edit causes a precondition failure. HTTP If-Match is a standard mechanism for preventing an update from silently overwriting a changed representation; the destination API must actually support and honour an appropriate validator.
If the condition fails, read both sides again and reassess. Do not resend the old value unconditionally. If there is no reliable conditional write, serialise changes for the record where possible and keep uncertain races visible for review.
Record the selected value, rule, affected field, source versions and confirmed destination result. Check that the sync's own write is not treated as a new competing business edit.
Cases with an A-only edit, B-only edit, two edits to one field and two edits to separate fields reveal different faults. Compare the resulting records with expected values before accepting the rule.
![How to choose the right idempotency key for an event: Keep the same idempotency key for retries of one action; use a new key for a new action.; Write: one [effect] for each [identity], e.g. one standard invoice per approved order.; Check stability, uniqueness, scope and lifetime; include tenant ID for tenant-scoped IDs. Choosing an idempotency key for an event](/covers/choosing-an-idempotency-key-for-an-event-640.webp?v=39704930)