Skip to content

IRN Failures

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

Purpose

Diagnose a document that will not obtain a reference number, and distinguish a fixable fault from one that statute makes permanent.

Audience

Support teams, tax operations, administrators.

Prerequisites

  • The document number, the exact message, and the request identifier
  • Access to the document in the application
  • NIC Error Codes to hand

Steps

The decision tree

  A document has no reference number
        |
        v
  Is it visible in the workbench at all?
        |
        +-- No --> Is it in the Correction Cockpit?
        |            |
        |            +-- Yes --> QUARANTINED. Validation failed.
        |            |            Read the per-field messages. -> Path A
        |            |
        |            +-- No ---> Was it ever accepted?
        |                          Query its status by document number.
        |                          +-- Not found --> It never arrived. -> Ingest Failures
        |                          +-- Found ------> Refresh; check registration access
        |
        +-- Yes --> What is its status?
                      |
                      +-- Awaiting generation --> Nobody has generated it yet. -> Path B
                      |
                      +-- Failed ---------------> Is there a numbered error?
                      |                             +-- Yes --> Government rejection. -> Path C
                      |                             +-- No ---> Provider or platform. -> Path D
                      |
                      +-- Cancelled ------------> Already cancelled. The number is consumed
                      |
                      +-- Registered -----------> It worked. The reporter is looking in
                                                   the wrong place, or at the ERP, which
                                                   may not have received write-back

Path A — quarantined

Step Action
Symptoms The document is absent from the workbench and present in the Correction Cockpit
Root cause It failed Complifly's own validation, before any government call
Checks Read every message, not just the first. Note the field name on each
Resolution Correct in the cockpit and promote — or, if the cause is systemic, fix the source and reload
Validation The document promotes and appears in the workbench
Escalate when A message names a field the document clearly does contain, which suggests a mapping fault

If every document from one ERP fails the same way, the cause is the mapping template or the master data. Fixing documents one at a time will not keep pace with the next batch.

Path B — awaiting generation

Step Action
Symptoms The document sits ready, with no reference number
Root cause Generation has not been attempted. It is a deliberate act unless automatic generation is enabled
Checks Is automatic generation on? Does the user hold generation authority? Is the reporting window still open?
Resolution Generate it, or have someone with authority do so
Validation The status becomes registered, with a reference number and signed QR stored
Escalate when Generation is attempted and fails — follow Path C or D

Check the reporting window first. A document accumulating age here is on a statutory clock with no remedy at the end of it.

Path C — a numbered government rejection

Step Action
Symptoms Generation failed with a number such as 2150 or 2164
Root cause A government rule was broken
Checks Look the code up in NIC Error Codes and read the classification
Resolution Depends entirely on the classification — see the table below
Validation The corrected document registers
Escalate when The code is not documented, or the documented resolution does not apply
Classification What to do
you Correct the data at source and retry
statute No fix exists. Route to the tax lead for the lawful alternative
admin Configuration; route internally
support Raise a ticket with the code and request identifier

Path D — failure with no government code

Step Action
Symptoms Generation failed, with no numbered rejection
Root cause The request did not reach the government, or the operation is unavailable
Checks Run the provider connection test. Check credential expiry. Check the egress address. Check the capability state for this operation
Resolution Restore connectivity or credentials; if it is a capability limitation, use the documented alternative
Validation The connection test passes and generation succeeds
Escalate when The connection test passes but generation still fails

The four situations with no fix

Situation Why The only path forward
Duplicate — the number is consumed Permanent at the government, even after cancellation Issue under a new number
Reporting window expired Cannot be reopened by anyone Consult the tax lead
Counterparty registration cancelled Not in your control Contact the counterparty
Cancellation window closed Statutory A credit note, not a cancellation

Recognising these early saves a great deal of wasted effort. None is a support ticket.

Validation

Check Pass condition
The right path was taken The tree's branch matches the observed symptom
The classification was read You know whether it is yours, statutory, or support's
The fix is verified The document reaches registered status
Systemic causes identified If the same failure recurs, the source is fixed
Evidence captured on escalation Document number, code, message, request identifier

Troubleshooting

Symptom Cause Action
The document is nowhere Quarantined, or never arrived Check the cockpit, then query status by number
The user says it is missing, the status says registered They are looking at the ERP, which has not received write-back Check write-back before investigating registration
Duplicate on a number never used Series restarted, or shared with another system Fix the series before sending more
Generation fails only for one registration Provider credentials scoped per registration Confirm the credential covers it
Generation fails for everything, suddenly Credentials expired, or the egress address changed Run the connection test
A document keeps returning to quarantine The correction missed a message Re-read all of them; several may apply
Registered but Branded Print fails A rendering or configuration problem See Print Configuration
Registered but the official NIC copy will not print The 2-day window has closed and no copy was cached Not recoverable. Use Branded Print, which renders from the signed data captured at generation
Window expired on a batch A backlog loaded outside the window Expected. Agree the approach before loading a backlog