Playbook18 min read

Integration reliability: retries, uncertain sends and reconciliation

Retry OrdoGrid API calls without duplicate invoices or payments: stable external_id, Integration ID, Idempotency-Key, error codes, uncertain Peppol sends, alerts.

Updated
Content owner
Integration operations
For
Integration engineers · Integration operations · Finance controllers

At a glance

Give every business event one stable external_id under a fixed Integration ID, classify each response by its code before retrying, and look the event up after any timeout. Never answer a lost response with a new ID, and hold an uncertain Peppol send until OrdoGrid has confirmed its outcome.

Before you begin

  • Business plan including public API access
  • An OrdoGrid API key with only the Permissions it needs and a known Integration ID
  • A source system that can derive one stable ID per invoice, credit note and payment
  • Sanitised request and response logs, and a named owner for the retry queue

What you will achieve

  • A retry policy driven by error codes, with tested limits and backoff
  • No duplicate invoice, credit note or payment after a timeout, a crash or a key rotation
  • A monitored queue in which every held item has an owner and a decision
On this page

An integration is reliable when it can recover a business transaction after a lost HTTP response, a crashed worker or an unclear Peppol hand-over, without creating a second invoice, payment or transmission. "Retry three times" does not achieve this: some requests are refused before anything is written, others fail after OrdoGrid has already numbered the invoice or recorded the cash. This playbook sets out which identities to keep, how to classify each response, when to retry, when to hold and what to monitor.

It is for developers and operators of connectors on the OrdoGrid public API (/api/v1). Keys, permissions and mapping are in Public API integration; coordinating a live incident is in Invoice incident response; badge meanings are in Peppol delivery status. The full contract is the API reference.

Why duplicates are costly

What applies
The lawEach invoice has a unique sequential number in the outgoing-invoice book (Royal Decree no. 1, art. 5 §1 1°) and must be issued by the 15th of the month after the chargeable event (art. 4 §1). A document correcting a structured invoice is issued in the same format (art. 53 §2bis VAT Code), so a duplicate sent on Peppol is corrected by a credit note on Peppol (FAQ Q5), not deleted.
FPS FinancePeppol does not recognise duplicates; detecting them is the user's and the software's job (specific FAQ, Q4). Delivery usually takes minutes to a couple of hours; delays over one working day go to your software supplier (Peppol FAQ, Q9).
OrdoGridDurable external_id identities, 24-hour Idempotency-Key replay, one outbound transmission per invoice, and a block on resending while an outcome is unclear. They only work if your connector keeps the same identities.
Our recommendationThe ledger, retry limits, holds and alerts below: suggestions to adapt to your volumes, not OrdoGrid service commitments.

Four guards and their limits

GuardScope and lifetimePreventsDoes not prevent
Idempotency-Key headerThe calling API key; 24 hoursA second execution of the same POST: an identical retry returns the stored success with Idempotent-Replay: trueA changed body under the same key (409 IDEMPOTENCY_KEY_REUSED); a rerun after a failed call (the key is released); PATCH, PUT, DELETE; a retry under a rotated key
Document external_idCompany, Integration ID and document kind; no expiry, survives rotationA second invoice or credit note for the same source transactionA new ID; another Integration ID; any change to the creation body (409 EXTERNAL_ID_REUSED)
Movement external_idCompany and Integration ID, across all invoices and movement kinds; no expiryCounting the same cash twice: a retry returns the original with replayed: trueA change in amount, currency, method, occurrence time or reference, or the same ID on another invoice (EXTERNAL_ID_REUSED)
Peppol transmission guardOne transmission per invoice or credit noteA second transmission: an accepted send comes back with replayed: true, an unclear one is refusedA new invoice for the same sale; an emailed PDF

Send both headers and IDs: Idempotency-Key makes an immediate retry cheap, external_id makes recovery possible after 24 hours or a key change. The API accepts documents without external_id, but treat it as mandatory; on movements it is.

Integration ID
The namespace of an API key (integration_id in the API, Integration ID on the API keys page). Every external_id is looked up inside the namespace of the calling key. Up to 80 letters, digits, _, . or -; fixed at creation; the field defaults to default.

Keep an identity ledger

Keep one row per business event, not per HTTP request: source event and external_id (SO-58213), Integration ID (erp-prod), document kind, the exact body sent or its SHA-256, the Idempotency-Key, OrdoGrid id, number and peppol_document_id, each movement with all its fields, the last outcome with UTC time and code, and the queue state with its owner.

  1. Derive the ID from the business event (1 to 200 characters). A UUID per request switches off every guard above.
  2. Freeze the body at first submission and resend it unchanged. OrdoGrid fingerprints the whole creation body, so an ERP that rebuilds the payload with a corrected email address or due date triggers EXTERNAL_ID_REUSED.
  3. Omit number so the company series assigns it. Your own numbers plus a retry without external_id give 409 DOCUMENT_NUMBER_TAKEN.
  4. Put a readable source reference in each movement's reference; finance sees it in Movement history on the invoice's Settlement panel. Keep it identical on every retry.
  5. Protect the ledger. A correction is a new row pointing to the old one, never an edited ID.

Keep the namespace when keys change

On the API keys page (owners and administrators):

  1. Rotate issues a new key with the same name, Permissions, expiry date and Integration ID; the old key stops at once. Copy the new secret under Copy this key now: it is shown once.
  2. A replacement made with Create key needs the old Integration ID typed exactly. Left at default, its lookups return 404 and retries create new invoices or payments.
  3. The key list does not show the Integration ID: call GET /api/v1/me and compare api_key.integration_id with your ledger before restarting.
  4. HTTP replay records belong to the old key; after a rotation, recover through lookup by external_id.

Classify every outcome before you retry

Branch on the error code, never on the message text. Anything not listed: treat the outcome as unknown and look the event up.

Documents and cash movements

ResponseWritten?Action
201; or Idempotent-Replay: true or replayed: true (200 on movements)YesRecord id and number. A replay is the first result again, not a new sale or payment
Timeout, connection reset, 5xx without a listed codeUnknownLook up by external_id before anything else: GET /api/v1/invoices/lookup or /api/v1/credit-notes/lookup for documents, GET /api/v1/invoices/payments/lookup for movements
400 VALIDATION_ERROR, UNKNOWN_FIELD, INVALID_AMOUNT_PRECISION, CURRENCY_MISMATCH, INVALID_OCCURRENCE_TIME, UNKNOWN_VAT_TYPENoFix the mapping; resend the corrected body under the same external_id (if that returns EXTERNAL_ID_REUSED, see Edge cases). No automatic retry
401 API_KEY_EXPIRED, API_KEY_REVOKED, INVALID_API_KEY; 403 INSUFFICIENT_SCOPENoStop the queue. INVALID_API_KEY: check the configured secret. Key revoked by Rotate: install the new secret. Expired or otherwise revoked key, or missing Permissions: Rotate cannot help (it keeps the Permissions and expiry date and is not offered on an expired or revoked key), so make a new key with Create key, type the old Integration ID exactly, check it with GET /api/v1/me, then resume with the same identities
429 RATE_LIMITEDNoWait Retry-After seconds; slow down
409 IDEMPOTENT_REQUEST_IN_PROGRESSFirst call still runningWait a few seconds; retry with the same key and body
409 EXTERNAL_OPERATION_IN_PROGRESSAnother call holds the identityWait more than two minutes (the worker lease), then look up
409 IDEMPOTENCY_KEY_REUSED or EXTERNAL_ID_REUSEDFirst version exists or is reservedPark; compare the stored and new bodies; never bypass with a new key or ID
409 SETTLEMENT_CONFLICTNoConcurrent change to the invoice; retry with the same external_id after backoff
409 OVERPAYMENT, OVER_REFUNDNoDo not retry; check whether the cash was recorded under another ID
409 DOCUMENT_FINANCIAL_CONTENTS_LOCKED on an editNoA payment is recorded, the invoice is prepared for or sent on Peppol, or the document is a saved credit note: do not edit; correct with a new credit note or invoice
502 DOCUMENT_CREATEDYes, PDF or attachments unfinishedResend the identical body under the same external_id to complete it; without one, use details.document_id and never create again

Rate limits are per key and per minute (120 by default); read X-RateLimit-Remaining and X-RateLimit-Reset (seconds) instead of hard-coding the number.

Peppol sends

Read GET /api/v1/peppol/invoices/{id}/status (or the credit-note equivalent) with peppol:read. transmission_state is OrdoGrid's hand-over to its access point; status follows delivery and matches the badges in Peppol → Outbox (processed is Traité).

Code or transmission_stateMeaningAction
403 PEPPOL_APPROVAL_REQUIRED, PEPPOL_LIMIT_REACHEDNothing created or sentSign the Autorisation Peppol or change plan in Billing & Subscription; resend the same request
PEPPOL_CLIENT_NOT_FOUNDNot transmitted; with POST /api/v1/peppol/send the invoice already existsCheck the VAT number with GET /api/v1/peppol/participants/{vat_number}, then send the existing invoice; if the customer cannot receive on Peppol, deliver that same invoice another way
preparing, 409 PEPPOL_TRANSMISSION_IN_PROGRESSXML being built and archivedWait at least five minutes, then read the status
prepared, preparation_failedNot handed overFix any cause (such as a missing PDF); send the same invoice again
acceptedThe access point took it; not the buyer's acceptanceFollow status until processed
rejected, PEPPOL_TRANSMISSION_REJECTEDExplicitly refusedFind the cause; a retry resends the same archived bytes. Wrong content: Fix a failed Peppol send or a rejected Peppol invoice
sending, uncertain, PEPPOL_TRANSMISSION_UNCERTAINMay already be on the networkHold: no new invoice, no emailed copy; reconcile with OrdoGrid support
409 PEPPOL_HISTORY_RECONCILIATION_REQUIREDOlder duplicate transmissions existContact OrdoGrid support
PEPPOL_ARCHIVE_HASH_MISMATCH, XML_NOT_AVAILABLE, PDF_NOT_AVAILABLEArchived file cannot be served as storedEscalate; never present a regenerated file as the original

OpenPeppol's Invoice Response specification separates transport acknowledgements from the buyer's business decision, and buyers need not respond. Keep transmission state, customer response and settlement in separate fields: delivered is neither accepted nor paid.

The retry loop

Our suggested starting values, not product limits: backoff of 1, 2, 4, 8, 16 and 32 seconds, capped at 60, with ±20% jitter; six attempts per event, then park it as held with a reason. Waits for 429 do not count. Keep one Idempotency-Key per business operation (SO-58213-create) on every retry; change the body only after a 4xx, when OrdoGrid has released the key.

while attempts < 6:
  r = POST /api/v1/invoices  (frozen body, same Idempotency-Key)
  2xx                            -> done(r.id, r.number)
  429                            -> wait Retry-After; continue
  permanent 4xx or *_REUSED      -> park(code); stop
  502 DOCUMENT_CREATED           -> attempts += 1; continue   (identical resend completes it)
  EXTERNAL_OPERATION_IN_PROGRESS -> wait 150 s
  l = GET /api/v1/invoices/lookup?external_id=...
  200 -> done(l.id, l.number)    409 -> wait 150 s    404 -> retry
  attempts += 1; wait backoff(attempts)
park("retry budget used")

After 24 hours the Idempotency-Key expires; an identical retry is still protected by external_id. PATCH, PUT and DELETE have no replay: after a lost response, GET the document and compare before applying the change again.

Worked example: timeout, rotation, bank payment

Verhaeghe Technics BV (Kortrijk) invoices from its ERP with a key named "ERP production", Integration ID erp-prod. Sales order SO-58213 is for Brasserie Lambert SRL (Namur), which receives on Peppol: 8 h of machine servicing × €95.00 = €760.00 and one portable pump at €1,240.00 (no work on the building, so no construction reverse charge), so €2,000.00 net + €420.00 VAT at 21% = €2,420.00.

12 October 2026, 14:02 UTC (16:02 in Brussels). POST /api/v1/peppol/send with external_id SO-58213 and Idempotency-Key SO-58213-send times out after 30 seconds.

  1. Classify. Unknown outcome: no resend.
  2. Look up. GET /api/v1/invoices/lookup?external_id=SO-58213 returns 200: invoice F-2026-0418 exists (this route creates the invoice before sending).
  3. Read the transmission. Status shows transmission_state uncertain, transmitted: false. The ledger row is held; owner Anke Peeters; next check 15:00 UTC.
  4. Resolve. At 15:00 the state is accepted; at 15:20 status is processed (Traité in Peppol → Outbox). One invoice, one transmission, €2,420.00 receivable.

A naive connector retrying three times with a fresh UUID each time would have created and sent F-2026-0419 to F-2026-0421: 3 × €2,420.00 = €7,260.00 of extra receivables, including €1,260.00 VAT, which Peppol does not flag as duplicates. Each needs its own Peppol credit note (NC-2026-0031 to NC-2026-0033) and a call to the customer.

20 October. The administrator clicks Rotate; GET /api/v1/me still shows erp-prod. At 09:15 UTC the bank feed records the first transfer:

{"external_id":"bank-20261020-0144","amount":"1000.00","currency":"EUR","method":"bank_transfer","occurred_at":"2026-10-20T09:12:00Z","reference":"Statement 203 line 14"}

The response is lost. The stored body is resent with the same Idempotency-Key: the original 201 comes back with Idempotent-Replay: true (without the header, or after 24 hours, the durable identity answers 200 with replayed: true). outstanding is "1420.00" either way. A rebuilt reference such as "Stmt 203/14" would have produced 409 EXTERNAL_ID_REUSED.

Had the connector switched, between the lost response and the retry, to a key made with Create key and left at default, that retry would have recorded a second €1,000.00: outstanding €420.00 while the customer owes €1,420.00, discovered only on 3 November when the real €1,420.00 payment is refused with OVERPAYMENT. Instead, payment bank-20261103-0029 brings outstanding to "0.00" and settlement.status to settled.

Edge cases and common mistakes

SituationRight action
Lookup returns 404 after a timeoutCheck the namespace with GET /api/v1/me first, then resend the identical body under the same external_id; never a new ID "because it does not exist"
EXTERNAL_ID_REUSED after an order was edited in the ERPFinance decides which version is right; an existing wrong invoice gets a credit note and a new invoice. Do not append -v2
A corrected body returns EXTERNAL_ID_REUSED after a refusal raised during creation (such as OVERPAYMENT on creation prepayments or DOCUMENT_NUMBER_TAKEN)The identity stays tied to the refused body. If lookup still answers 409 EXTERNAL_OPERATION_IN_PROGRESS well after two minutes, nothing was saved: have OrdoGrid support confirm, then use a new ID and link both in the ledger
IDEMPOTENT_REQUEST_IN_PROGRESS for more than a few minutesLook up; if absent, resend the identical body with a new Idempotency-Key; the external_id still blocks a duplicate
One transfer paying two invoicesMovement IDs are unique across invoices: bank-20261020-0144-a and -b
Wrong amount recordedA reversal always cancels the full movement: reverse it, then record the right amount under a new ID
Customer cannot find an invoice marked TraitéDelivered to its Peppol provider: the customer checks there. Do not resend or email it

Monitor business outcomes, not only uptime

MetricSuggested alertOwner
Oldest unsubmitted eventOlder than 30 minutes in office hoursOperations
Oldest held itemOlder than one working dayQueue owner
Sends in sending or uncertainAny older than 4 hoursIntegration operations
Events not invoiced, 15th-of-next-month deadline within 5 working daysAnyFinance
4xx refusals per day by codeA new code, or doubling day on dayIntegration developer
Replayed responses / requestsAbove 5% for an hourIntegration developer
Daily source totals against document_total and paymentsAny difference other than €0.00Controller

Count requests apart from business events: a replay is not new revenue. Log codes, IDs and UTC times, never the secret (ik_live_…) or the Authorization header. Read every list page (limit up to 100, offset) with stable filters and record the extraction window; see Month-end reconciliation.

Prove recovery before go-live

OrdoGrid has no sandbox or Peppol test mode: every call acts on real data, and "send": false still creates a numbered invoice. Where possible, test in a separate company kept for acceptance (Créer une nouvelle entreprise, create a new company) with its own key; otherwise plan a credit note per test invoice. Simulate uncertain or rejected sends with recorded responses in your own client.

ScenarioExpected
Create, then identical retry with the same key, then with a new key201, then 201 with Idempotent-Replay: true twice; one invoice
Same key, other body409 IDEMPOTENCY_KEY_REUSED; item parked
Same external_id, other body409 EXTERNAL_ID_REUSED; item parked, finance alerted
Two workers, same eventOne 201; the other an in-progress 409 or a replay
Payment, then identical retry with a new key201, then 200 with replayed: true; balance reduced once
Payment above outstanding409 OVERPAYMENT; no retry
Burst over the limit429 with Retry-After; nothing lost
Rotate, then replay earlier eventsReplays only; /me shows the same Integration ID

Accept when every event has one OrdoGrid identity, settlement matches the source, no uncertain send was repeated, and a deputy can work the held queue from the ledger alone. Hand over the decision tables, key owner, Integration ID, ledger location, thresholds and support contact. After an incident, reconcile the whole affected population before declaring recovery (Invoice incident response).

Evidence to keep

  • The ledger: frozen bodies or their hashes, Idempotency-Key values, every outcome with UTC time and code.
  • Per Peppol send: peppol_document_id, the transmission_state history, and the exchanged XML from GET /api/v1/peppol/documents/{id}/xml (Peppol document ID, not invoice ID; peppol:read), plus /pdf. OrdoGrid checks both against the SHA-256 hashes in transmission_snapshot.
  • Key changes (who, when, Integration ID before and after) and, per held item, the reason, checks, releaser and support exchange.
  • Invoices are kept seven years from 1 January after the year of issue; OrdoGrid gives no legal-archiving guarantee, so keep your own copy (Archiving invoices in Belgium).

FAQ

How long should we wait before retrying after a timeout?

Look up first instead of waiting. If the document exists, record it; if another call holds the identity, wait more than two minutes; if lookup returns 404, resend the identical body with backoff.

Can we reuse the same Idempotency-Key after an error?

Yes. OrdoGrid stores only successful responses and releases the key after a failure, so it can carry a corrected body after a 4xx. Within 24 hours of a success, a different body under that key is refused.

Why do we get EXTERNAL_ID_REUSED when only the description changed?

For documents the whole creation body counts, including descriptions, email addresses and due dates. For movements the amount, currency, method, occurrence time and reference count. Resend the stored body or let finance decide.

Is it safe to call the Peppol send endpoint again for the same invoice?

Yes, if the call targets the same invoice: the invoice's own send route, or POST /api/v1/peppol/send repeated with the same external_id (without one, that route creates a new invoice). An accepted transmission is returned with replayed set to true, a rejected one resends the archived bytes, an uncertain one is refused. A new invoice for the same sale or an emailed copy is not safe.

Does rotating an API key break duplicate protection?

Not with Rotate, which keeps the Integration ID. Only the 24-hour Idempotency-Key replay stays with the old key. A key made with Create key needs the same Integration ID typed by hand.

Can we test retries in a sandbox?

No. There is no sandbox or Peppol test mode. Use a separate acceptance company where possible, and simulate Peppol outcomes with recorded responses.

Sources and references