Integration reliability: retries, uncertain sends and reconciliation
Operate financial integrations safely through duplicate protection, external lookup, rate limits, credentials, queue control and archived evidence.
- Updated
- Content owner
- Integration operations
- For
- Integration operations · Backend engineers · Service delivery leads
At a glance
Preserve durable financial identities, classify outcomes before retrying and reconcile ambiguous network delivery before resending.
Before you begin
- Stable document and movement external identities
- Access to sanitized request/response records and the live API contract
- A queue owner and a finance escalation contact
What you will achieve
- A retry policy based on actual outcome
- No duplicate financial records from lost responses
- An owned backlog with financial and delivery reconciliation
On this page
Reliability is the ability to recover the business transaction when an HTTP response, worker or network acknowledgement is missing. “Retry three times” is not a financial recovery policy. Some failures reject a request safely; others occur after a numbered invoice or cash movement has already been committed.
Preserve an identity ledger
Store source transaction ID, integration namespace, document kind, payload fingerprint, product ID/number and latest known outcome. For cash, store the source tender/refund ID and linked invoice. Protect the ledger from casual edits: changing an ID after a timeout defeats duplicate protection.
OrdoGrid's durable document identity is scoped by company, integration and document kind. Movement identities are scoped by company/integration across invoices and movement kinds. Recreating or rotating a key does not release them; preserve the integration namespace.
| Control | Owner | Verification |
|---|---|---|
| Identity generation | Integration developer | Same business event gives the same ID |
| Retry/outcome policy | Service engineer | Lost response and replay example |
| Queue and rate limiting | Operations | Backlog age and header handling |
| Financial reconciliation | Controller | Source-to-settlement bridge |
| Network ambiguity | Provider liaison | Receipt/rejection evidence before resend |
Use both layers of duplicate protection
Send Idempotency-Key on retryable writes. Identical HTTP retry returns the cached response where available; reusing the key with a different body is refused. Its 24-hour lifetime and API-key scope are not a substitute for stable external_id values.
Durable document retries return the first completed document response. Movement retries return the original movement with current settlement and replayed: true. Reconcile with those identifiers even after response-cache expiry or credential replacement. Never generate a new key per retry in a way that also changes the financial identity.
Classify before scheduling a retry
| Outcome | Operator action |
|---|---|
| Invalid fields, currency or precision | Correct mapping; no blind retry |
| Missing scope or registration approval | Fix entitlement/approval through its owner |
| 429 | Respect Retry-After and rate-limit reset |
EXTERNAL_OPERATION_IN_PROGRESS | Keep identity; wait and reconcile |
| Lost create or movement response | Lookup by external ID; retry identical content if needed |
EXTERNAL_ID_REUSED | Investigate original payload and the appropriate correction |
PEPPOL_TRANSMISSION_UNCERTAIN | Hold resend; reconcile with provider evidence |
| Archive hash mismatch | Escalate integrity/retrieval; preserve evidence |
An execution lease can expire while the durable accounting identity remains. Treat a resumed operation as recovery of that record, not a fresh business event.
Use bounded backoff with jitter in your client for recoverable contention or temporary availability failures. Keep the retry budget and maximum backlog age under an operational owner. Those are choices for your integration, not product guarantees.
Distinguish document commit from network exchange
A send can first create the invoice and then encounter a network problem. Look up the financial record and inspect transmission state separately. Known rejected transmission may be retried with the same issued bytes when permitted. An ambiguous transmission may have reached the network, so automatic resend is held.
OpenPeppol's Invoice Response specification distinguishes network acknowledgement from a buyer's business decision. A delivered message does not prove acceptance or cash receipt. Keep settlement, transport state and customer response in separate monitoring fields.
Example: recovery after key rotation
ERP invoice order-4711 was created under namespace erp; its successful response was lost. The key is subsequently rotated. The connector starts with /me, confirms the same company and namespace, then looks up order-4711. It recovers the existing numbered invoice.
The connector later synchronizes a deposit using the same source tender identity. The movement replay identifies the original cash record instead of adding another deposit. If the connector had recreated the key with a different namespace and invented a new invoice ID, it would have bypassed the intended recovery contract.
Observe the business, not just uptime
Track unattempted backlog, oldest held item, successful commits, permanent mapping refusals, uncertain sends and reconciliation differences. Count requests separately from business events because a replay is not new revenue. Log sanitized error codes, IDs and timing; never record bearer secrets.
Read all list pages with consistent filters. Where extraction overlaps writes, record the snapshot interval and reconcile late changes. Define an alert owner and escalation path for growing backlog or financial differences using your actual service process.
Accept recovery and hand over
Exercise lost response, concurrent creation, expired HTTP replay window, credential rotation, rejected send and ambiguous send. Acceptance requires one financial identity per event, expected settlement, no duplicate transmission attempt in an uncertain case, and evidence that a deputy can follow the queue.
After an incident, reconcile the full affected population before declaring recovery. Give operations a decision table, key owner, external-ID ledger location, replay procedure and provider contact. Route unresolved commercial cases to finance, with impact and next action. Use incident response for coordination and API integration for the initial contract.