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 law | Each 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 Finance | Peppol 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). |
| OrdoGrid | Durable 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 recommendation | The ledger, retry limits, holds and alerts below: suggestions to adapt to your volumes, not OrdoGrid service commitments. |
Four guards and their limits
| Guard | Scope and lifetime | Prevents | Does not prevent |
|---|---|---|---|
Idempotency-Key header | The calling API key; 24 hours | A second execution of the same POST: an identical retry returns the stored success with Idempotent-Replay: true | A 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_id | Company, Integration ID and document kind; no expiry, survives rotation | A second invoice or credit note for the same source transaction | A new ID; another Integration ID; any change to the creation body (409 EXTERNAL_ID_REUSED) |
Movement external_id | Company and Integration ID, across all invoices and movement kinds; no expiry | Counting the same cash twice: a retry returns the original with replayed: true | A change in amount, currency, method, occurrence time or reference, or the same ID on another invoice (EXTERNAL_ID_REUSED) |
| Peppol transmission guard | One transmission per invoice or credit note | A second transmission: an accepted send comes back with replayed: true, an unclear one is refused | A 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_idin the API, Integration ID on the API keys page). Everyexternal_idis looked up inside the namespace of the calling key. Up to 80 letters, digits,_,.or-; fixed at creation; the field defaults todefault.
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.
- Derive the ID from the business event (1 to 200 characters). A UUID per request switches off every guard above.
- 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. - Omit
numberso the company series assigns it. Your own numbers plus a retry withoutexternal_idgive409 DOCUMENT_NUMBER_TAKEN. - 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. - 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):
- 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.
- A replacement made with Create key needs the old Integration ID typed exactly. Left at
default, its lookups return404and retries create new invoices or payments. - The key list does not show the Integration ID: call
GET /api/v1/meand compareapi_key.integration_idwith your ledger before restarting. - 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
| Response | Written? | Action |
|---|---|---|
201; or Idempotent-Replay: true or replayed: true (200 on movements) | Yes | Record id and number. A replay is the first result again, not a new sale or payment |
Timeout, connection reset, 5xx without a listed code | Unknown | Look 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_TYPE | No | Fix 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_SCOPE | No | Stop 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_LIMITED | No | Wait Retry-After seconds; slow down |
409 IDEMPOTENT_REQUEST_IN_PROGRESS | First call still running | Wait a few seconds; retry with the same key and body |
409 EXTERNAL_OPERATION_IN_PROGRESS | Another call holds the identity | Wait more than two minutes (the worker lease), then look up |
409 IDEMPOTENCY_KEY_REUSED or EXTERNAL_ID_REUSED | First version exists or is reserved | Park; compare the stored and new bodies; never bypass with a new key or ID |
409 SETTLEMENT_CONFLICT | No | Concurrent change to the invoice; retry with the same external_id after backoff |
409 OVERPAYMENT, OVER_REFUND | No | Do not retry; check whether the cash was recorded under another ID |
409 DOCUMENT_FINANCIAL_CONTENTS_LOCKED on an edit | No | A 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_CREATED | Yes, PDF or attachments unfinished | Resend 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_state | Meaning | Action |
|---|---|---|
403 PEPPOL_APPROVAL_REQUIRED, PEPPOL_LIMIT_REACHED | Nothing created or sent | Sign the Autorisation Peppol or change plan in Billing & Subscription; resend the same request |
PEPPOL_CLIENT_NOT_FOUND | Not transmitted; with POST /api/v1/peppol/send the invoice already exists | Check 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_PROGRESS | XML being built and archived | Wait at least five minutes, then read the status |
prepared, preparation_failed | Not handed over | Fix any cause (such as a missing PDF); send the same invoice again |
accepted | The access point took it; not the buyer's acceptance | Follow status until processed |
rejected, PEPPOL_TRANSMISSION_REJECTED | Explicitly refused | Find 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_UNCERTAIN | May already be on the network | Hold: no new invoice, no emailed copy; reconcile with OrdoGrid support |
409 PEPPOL_HISTORY_RECONCILIATION_REQUIRED | Older duplicate transmissions exist | Contact OrdoGrid support |
PEPPOL_ARCHIVE_HASH_MISMATCH, XML_NOT_AVAILABLE, PDF_NOT_AVAILABLE | Archived file cannot be served as stored | Escalate; 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.
- Classify. Unknown outcome: no resend.
- Look up.
GET /api/v1/invoices/lookup?external_id=SO-58213returns200: invoice F-2026-0418 exists (this route creates the invoice before sending). - Read the transmission. Status shows
transmission_stateuncertain,transmitted: false. The ledger row is held; owner Anke Peeters; next check 15:00 UTC. - Resolve. At 15:00 the state is
accepted; at 15:20statusisprocessed(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
| Situation | Right action |
|---|---|
Lookup returns 404 after a timeout | Check 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 ERP | Finance 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 minutes | Look up; if absent, resend the identical body with a new Idempotency-Key; the external_id still blocks a duplicate |
| One transfer paying two invoices | Movement IDs are unique across invoices: bank-20261020-0144-a and -b |
| Wrong amount recorded | A 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
| Metric | Suggested alert | Owner |
|---|---|---|
| Oldest unsubmitted event | Older than 30 minutes in office hours | Operations |
| Oldest held item | Older than one working day | Queue owner |
Sends in sending or uncertain | Any older than 4 hours | Integration operations |
| Events not invoiced, 15th-of-next-month deadline within 5 working days | Any | Finance |
4xx refusals per day by code | A new code, or doubling day on day | Integration developer |
| Replayed responses / requests | Above 5% for an hour | Integration developer |
Daily source totals against document_total and payments | Any difference other than €0.00 | Controller |
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.
| Scenario | Expected |
|---|---|
| Create, then identical retry with the same key, then with a new key | 201, then 201 with Idempotent-Replay: true twice; one invoice |
| Same key, other body | 409 IDEMPOTENCY_KEY_REUSED; item parked |
Same external_id, other body | 409 EXTERNAL_ID_REUSED; item parked, finance alerted |
| Two workers, same event | One 201; the other an in-progress 409 or a replay |
| Payment, then identical retry with a new key | 201, then 200 with replayed: true; balance reduced once |
Payment above outstanding | 409 OVERPAYMENT; no retry |
| Burst over the limit | 429 with Retry-After; nothing lost |
| Rotate, then replay earlier events | Replays 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-Keyvalues, every outcome with UTC time andcode. - Per Peppol send:
peppol_document_id, thetransmission_statehistory, and the exchanged XML fromGET /api/v1/peppol/documents/{id}/xml(Peppol document ID, not invoice ID;peppol:read), plus/pdf. OrdoGrid checks both against the SHA-256 hashes intransmission_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
- OrdoGrid public API reference: idempotency, external lookup and error codes
- Peppol BIS Invoice Response 3.2: transport acknowledgements versus business responses
- FPS Finance, e-invoicing FAQ: specific questions (Q4 duplicates, Q5 credit notes)
- FPS Finance, Peppol FAQ: delivery delays (Q9)
- Law of 6 February 2024, art. 53 §2bis VAT Code: corrective documents in the same structured format (Belgian Official Journal, 20.02.2024)
- Royal Decree no. 1, art. 4 and 5: issue deadline and sequential numbering (Justel, consolidated)