Versioning, retries, and reconciliation
Keep integrations understandable as schemas, procedures, and network conditions change.
Track the versions that change meaning
An API version, entity-definition version, operating-record revision, mapping version, and event-schema version describe different things. Preserve the applicable versions when they affect interpretation or replay.
Review release and deprecation information for your deployment. An added optional field may be compatible; a changed unit, authorization boundary, or state meaning can require explicit consumer review.
Retry the same intention safely
For a transient failure, use bounded backoff and the documented retry guidance. If the contract supports an idempotency key, keep it stable for the same intended operation and follow its scope and expiry rules.
Do not retry every failure. A validation failure needs corrected input; a permission failure needs an authority decision; an unknown outcome needs reconciliation. Blind retries can duplicate external effects.
Reconcile both sides
- Retain source and destination identities plus the original operation reference.
- Check the recorded outcome of an uncertain attempt before repeating it.
- Compare relevant records and balances at an agreed interval.
- Assign unresolved mismatches to an owner with supporting context.
- Record corrections and replay decisions so recovery can be explained.
Use a small release checklist
- Contract and mapping versions are identified.
- Duplicate, delayed, out-of-order, and conflicting inputs are tested.
- Permission boundaries and credential revocation are checked.
- Failure monitoring has an owner and an escalation path.
- Rollback or compensating actions are understood.
- Required operational review and validation evidence is retained.