How do I debug an EFRIS error?

Start by identifying whether the failure is envelope level or item level. An envelope-level failure puts the code in returnStateInfo.returnCode and means nothing was recorded. An item-level failure returns returnCode 00 at the envelope while individual lines are refused inside the decrypted payload, so a batch can be partly accepted. Always branch on the numeric code rather than the message text, because URA rewords messages between releases. Then log the full decrypted payload, since the useful detail is often in a nested field rather than in returnMessage, and recompute your summary block from taxDetails, which is the most common source of rejections.

What is the most common cause of EFRIS invoice rejections?

The summary block. URA recomputes summary.netAmount, summary.taxAmount and summary.grossAmount from the taxDetails you send and rejects any disagreement. netAmount must equal grossAmount minus taxAmount (error 1343), taxAmount must include excise duty (error 1344), and grossAmount must exclude tax category 05 because excise is already embedded in the standard-rate gross (error 1345). summary.itemCount must also exclude discount lines, which are entries in goodsDetails with discountFlag 0 (error 1304).

EFRIS error codes

What each URA rejection actually means, and how to fix it. Learned by submitting documents to the live service and reading what came back — where this disagrees with URA's specification, this describes what the service does.

How to read a URA rejection

Failures arrive in two different places and they mean different things.

Envelope level — the call itself failed and nothing was recorded. The code is in returnStateInfo.returnCode:

{"returnStateInfo": {"returnCode": "1345", "returnMessage": "..."}}

Item level — the call succeeded but individual lines were refused. The envelope still reads 00 while per-item status sits inside the decrypted payload. A batch can be partly accepted, so treating HTTP 200 plus returnCode 00 as success silently loses documents.

Branch on the code, never on the message. URA rewords returnMessage between releases and some messages return in mixed language. The number is the stable contract.

Every documented code

15Data decryption error — the session key expired; redo T104 306A credit note has already been issued against that invoice 676Unit-rate excise requires havePieceUnit "101" and piece fields 1304summary.itemCount must exclude discount lines 1343summary.netAmount must equal grossAmount minus taxAmount 1344summary.taxAmount must include excise duty 1345summary.grossAmount must exclude excise duty 1462A credit note must mirror the original line's excise fields 1526pageSize must be 99 or less, despite the documented 100 2253The seller's reference number has already been issued 2831The excise taxDetails group needs a taxRateName

Debugging something not listed here

Log the whole decrypted payload — the useful detail is often nested rather than in returnMessage.
Establish whether the failure is envelope level or item level.
Recompute your summary from taxDetails and compare. Summary arithmetic is the single most common source of rejections.
Confirm the session key is 16 bytes and freshly negotiated — see the protocol guide.

The EFRIS API Kit handles this case already — it is one of the rejections the library was calibrated against. This page stays free either way.