KSEF-21178:KSeF UPO (Urzędowe Poświadczenie Odbioru) not found
Fix: Verify the invoice reached terminal status before requesting UPO. Check the KSeF number format and the requesting user permissions.
You requested the UPO (Urzędowe Poświadczenie Odbioru — the official acceptance confirmation) for a KSeF invoice, but the system could not find a UPO matching the provided criteria. Either the invoice has not yet been assigned a UPO, or the search parameters (referenceNumber, KSeF number, sessionReferenceNumber) do not identify a valid invoice.
Engine Classification
Financial or legal field · Modification blocked by policy
Reason: Not an XML validation error — this is an API retrieval mismatch. Fixing requires correcting the request parameters or waiting for the invoice to reach terminal state.
What is KSEF-21178?
KSEF-21178 is a fatal validation rule defined in the KSeF 2.0 specification (PL national rules). It validates the upo and related UPO retrieval endpoints. Common root causes: the invoice is still in processing state (UPO not yet generated), the KSeF number in the request path is malformed, or the requesting entity does not have permission to see the UPO for that invoice. The response payload uses HTTP 404 with body code 21178. element under invoices > {ksefNumber} in the UBL invoice XML.
When this rule fires, the invoice is rejected by Peppol access points and never reaches the buyer.
Target path: The 21178 code surfaces on GET /invoices/{ksefNumber}/upo and related UPO retrieval endpoints. Common root causes: the invoice is still in processing state (UPO not yet generated), the KSeF number in the request path is malformed, or the requesting entity does not have permission to see the UPO for that invoice. The response payload uses HTTP 404 with body code 21178.
Why This Error Matters
The UPO is the legal proof of receipt for a KSeF invoice — the Polish equivalent of a Peppol MLR. Downstream systems (accounting, archiving, dispute handling) rely on the UPO to confirm the invoice is officially in circulation. A UPO not-found error blocks that entire downstream chain.
KSEF-21178 is a hard failure — the invoice must be corrected and re-sent before it can reach the recipient.
Blocks archiving and legal-proof workflows. Downstream teams (finance, legal, audit) cannot confirm invoice acceptance without the UPO.
Validator Behavior
- ·Causes invoice rejection
- ·Error returned: KSEF-21178
- ·Specification: KSeF 2.0
How to Fix It
XML Example
Generic example based on the rule's target XPath. Your actual XML structure may differ.
<!-- Triggers validation error --> <upo and related UPO retrieval endpoints. Common root causes: the invoice is still in processing state (UPO not yet generated), the KSeF number in the request path is malformed, or the requesting entity does not have permission to see the UPO for that invoice. The response payload uses HTTP 404 with body code 21178.></upo and related UPO retrieval endpoints. Common root causes: the invoice is still in processing state (UPO not yet generated), the KSeF number in the request path is malformed, or the requesting entity does not have permission to see the UPO for that invoice. The response payload uses HTTP 404 with body code 21178.>
<!-- Corrected --> <upo and related UPO retrieval endpoints. Common root causes: the invoice is still in processing state (UPO not yet generated), the KSeF number in the request path is malformed, or the requesting entity does not have permission to see the UPO for that invoice. The response payload uses HTTP 404 with body code 21178.>VALID_VALUE</upo and related UPO retrieval endpoints. Common root causes: the invoice is still in processing state (UPO not yet generated), the KSeF number in the request path is malformed, or the requesting entity does not have permission to see the UPO for that invoice. The response payload uses HTTP 404 with body code 21178.>
Technical Reference
The 21178 code surfaces on GET /invoices/{ksefNumber}/upo and related UPO retrieval endpoints. Common root causes: the invoice is still in processing state (UPO not yet generated), the KSeF number in the request path is malformed, or the requesting entity does not have permission to see the UPO for that invoice. The response payload uses HTTP 404 with body code 21178.Common Causes
- ·Polling for UPO before the invoice has been fully processed
- ·Wrong KSeF number passed — often confusing invoice reference with KSeF number
- ·Missing permissions on the technical user requesting the UPO
- ·Batch session not yet closed
- ·Invoice was rejected — UPO is never issued for rejected invoices
Seeing this in production? The API handles KSEF-21178 automatically. See the fix response →
Commonly Seen In
Frequently Asked Questions
UPO (Urzędowe Poświadczenie Odbioru) is the official acceptance confirmation issued by KSeF once an invoice is accepted. It is the Polish e-invoicing equivalent of a Peppol MLR.
UPO generation is asynchronous. You must first poll invoice status until it reaches Accepted (200); only then is the UPO available for retrieval.
No. UPOs are issued only for accepted invoices. A rejection has its own error payload with the reason for rejection.
Exponential back-off starting at 2 seconds, capped at 60 seconds, for up to 5 minutes. If you still see 21178 after 5 minutes, escalate — the invoice may have failed silently.
Related Errors
Related Content
Last updated: 7 July 2026
Validate your invoice
Drop your XML here to check for KSEF-21178
Detect KSEF-21178 before submission
This error involves a financial field that can't be auto-modified. We'll flag it with a clear diagnosis so you can fix it at the source.