Skip to content

Ingest Failures

Applies to: e-Invoice · e-Way Bill · Which modules do I have?

Purpose

Diagnose documents that do not reach Complifly, arrive with wrong values, or are refused — and identify whether the cause is one document, the mapping, the credential, or the ERP.

Audience

Support teams, integration developers, administrators.

Prerequisites

  • The document number, and the ERP's own record of what it sent
  • The request identifier from the ERP's log, where available
  • Ingest API

Steps

The decision tree

  A document is not in Complifly, or is wrong
        |
        v
  Does the ERP believe it sent it?
        |
        +-- No ----> The ERP never sent it. -> Path A (ERP side)
        |
        +-- Yes --> What response did the ERP receive?
                      |
                      +-- None / timeout ------> Path B
                      |
                      +-- 401 / 403 -----------> Path C  (credential or scope)
                      |
                      +-- 409 duplicate -------> Path D
                      |
                      +-- 422 rejected --------> Path E  (validation)
                      |
                      +-- 201 accepted --------> It IS here.
                                                  Quarantined?     -> Path E
                                                  Not visible?     -> registration access
                                                  Values wrong?    -> Path F (mapping)

The first question is the important one, and it is frequently skipped. "The invoice is not in Complifly" and "the ERP never sent it" look identical from the Complifly side.

Path A — the ERP never sent it

Step Action
Symptoms No record on either side
Root cause The trigger did not fire, the document did not meet the selection criteria, or the job is not running
Checks Is the sending job running? Does the document meet the trigger's criteria? Is it in a state the trigger excludes, such as a draft?
Resolution Fix the trigger or the job on the ERP side
Validation The document is sent and accepted
Escalate when Never to Complifly — this is an ERP-side problem

Path B — no response received

Step Action
Symptoms The ERP recorded a timeout or connection failure
Root cause Network, proxy, or a timeout shorter than the operation
Checks Query the document status by number first. Then test connectivity from the ERP host. Then check proxy timeouts
Resolution If the document is present, record it and move on. If absent, fix connectivity and resend
Validation The status query and the ERP agree
Escalate when Connectivity is proven and calls still time out

Never resend blindly after a timeout. A timeout means the outcome is unknown, and a blind resend creates a duplicate — which is permanent.

Path C — credential or scope

Step Action
Symptoms Unauthorised or forbidden
Root cause Unauthorised means the credential is not accepted. Forbidden means it is accepted but the supplier registration is outside its scope
Checks For unauthorised: is the credential valid, unexpired, and are the clocks synchronised? For forbidden: which registration is the document for, and is it in scope?
Resolution Refresh or reissue the credential, or widen the scope deliberately
Validation The document is accepted
Escalate when The credential is confirmed correct and in scope and is still refused

Forbidden is a credential scope problem. Checking the user's role here is a dead end and a common detour.

Path D — duplicate

Step Action
Symptoms Rejected as a duplicate
Root cause The number already exists — sent twice, the series restarted, or two systems share a series
Checks Does the document already exist? Was it sent twice? Has the numbering series restarted?
Resolution If already present, reconcile. If the series restarted, fix the series before sending anything else
Validation The ERP shows the existing document; new documents do not collide
Escalate when The number was demonstrably never used

Path E — validation rejection or quarantine

Step Action
Symptoms Rejected with field-level errors, or held in the Correction Cockpit
Root cause Data faults, or a mapping fault presenting as data faults
Checks Read every message. Then ask: does this affect one document or all of them?
Resolution One document — correct it. Many — fix the mapping or the master data
Validation New documents pass
Escalate when A message names a field the document demonstrably contains

Path F — accepted, but values are wrong

Step Action
Symptoms The document is present with wrong dates, amounts, codes or type
Root cause Almost always the mapping template
Checks Compare the raw payload with the mapped result, field by field
Resolution Correct the mapping rule and re-test with real documents
Validation The mapped payload matches the ERP's values exactly
Escalate when The mapping is demonstrably correct and the values still differ

Wrong values are more dangerous than rejections. A rejection stops; a wrong value produces a legally incorrect registered document. Dates and amounts deserve particular scrutiny.

The four checks that resolve most cases

# Check Resolves
1 Query the document status by number "Is it actually here?"
2 Compare the raw payload with the mapped result Every mapping fault
3 Confirm the credential's registration scope Every forbidden response
4 Ask whether it affects one document or all Data fault versus systemic fault

Validation

Check Pass condition
Both sides examined The ERP's record and Complifly's both consulted
The mapped payload inspected Not merely the acceptance status
Scale established One document or all — determined before fixing
Systemic causes fixed at source Not handled document by document
No blind resends Status queried before any resend
The fix is verified New documents from the same source succeed

Troubleshooting

Symptom Cause Action
Documents stopped arriving overnight ERP job stopped, credential expired, or network changed Check in that order
Everything rejected as forbidden Credential scope excludes the registration Fix the scope
Everything rejected on one field Mapping fault Fix the template, not the documents
Dates a month out Date format token wrong Correct and re-test with an unambiguous date
Only the first line arrives Array notation wrong Test with a multi-line document
Duplicates after a network incident Blind resend Reconcile by status first
Works in testing, fails on real documents Cleaned samples used in testing Use raw ERP output
A wave of failures weeks after go-live A first edge case — an export, a credit note Test edge cases before go-live
Rejections invisible to the business The ERP swallows them Surface the field and message to a person who can act
Nobody noticed the feed stopped No ERP-side monitoring Alert on documents sent falling to zero