Fatoora errors: why your invoice was rejected and how to fix it
Fatoora rejects a document when a check fails and accepts it with a warning when the failure is not fatal. ZATCA, the Zakat, Tax and Customs Authority, documents these categories.
This page explains the official standard and does not replace it. Read the error message in the platform response: it is the reference.
Three possible outcomes for every document
The platform checks syntax first (well-formed XML that follows UBL 2.1), then content: EN 16931 rules, then the Saudi rules. It returns one of three outcomes.
- Valid
No error and no warning
For a standard (B2B) invoice the platform returns the document stamped with a QR code. For a simplified (B2C) one it returns a confirmation that it is valid.
- Accepted with warnings (202)
Accepted, with at least one warning
The document is accepted, so do not resubmit it. Read the warning and fix its cause: repeated non-compliance is investigated and may carry penalties.
- Rejected
One error rejects the whole document
A standard (B2B) invoice that was not cleared is not a valid tax invoice. Fix the cause and send a new document, as in the section below.
Rule categories: meaning, cause and fix
The table selects commonly hit rules; the standard has further families (BR-KSA-EN16931-nn, BR-KSA-F-nn, BR-KSA-CL-nn, BR-KSA-DEC-nn) with the same meaning structure. Causes are our reading, not the standard's text.
- BR-KSA-39BR-KSA-40BR-KSA-08
Seller VAT number and identifier
The seller needs a 15-digit VAT number that starts and ends with 3, and exactly one seller ID with an approved scheme: CRN, MOM, MLS, 700, SAG or OTH.
Usual cause: A short number or one not starting and ending with 3, two seller IDs, or symbols beyond letters and digits.FixCorrect the VAT number in the organization profile and keep one seller ID with a scheme from the list, using letters and digits only.
- BR-KSA-42BR-KSA-44BR-KSA-46BR-KSA-14
Buyer name and VAT number
A tax invoice and its notes need the buyer name. A buyer VAT number has 15 digits starting and ending with 3, and is not allowed on an export invoice.
Usual cause: An empty buyer name, an incomplete VAT number, a VAT number on an export invoice, or a buyer not registered for VAT and given no ID.FixEnter the buyer's official name. If the buyer is not VAT-registered, give an ID with an approved scheme such as NAT, IQA or CRN.
- BR-KSA-09BR-KSA-37BR-KSA-66BR-KSA-10BR-KSA-63BR-KSA-67
National address
The seller address needs street, building number (4 digits), postal code (5 digits), city, district and country. A buyer in Saudi Arabia needs the same fields.
Usual cause: A missing address field, a postal code that is not five digits, or a building number that is not four.FixComplete the national address for your organization and for the customer as registered, and check the digit count of building number and postal code.
- BR-CO-13BR-CO-14BR-CO-15BR-CO-16BR-CO-17BR-S-08BR-S-09BR-KSA-51BR-DEC-12
Totals, VAT and rounding
Every total equals its formula: total without VAT + VAT = total with VAT. Each category's VAT = taxable amount × rate ÷ 100, to two decimals at most.
Usual cause: Rounding that differs between line and invoice, a discount or charge left out of the category taxable amount, or totals computed from numbers other than those sent.FixCompute VAT on each category's taxable amount, round it to two decimals, then derive every total from the same rounded numbers you send in the file.
- BR-KSA-18BR-KSA-23BR-KSA-69BR-KSA-24BR-KSA-11BR-KSA-25BR-KSA-49
VAT category and exemption reason
The VAT category is S, Z, E or O. Exempt, zero-rated and not-subject lines each need a reason code, and category O takes a zero rate if one is given.
Usual cause: An unapproved category, an exemption with no reason code, or an education or health exemption (VATEX-SA-EDU, VATEX-SA-HEA) with no national ID for the buyer.FixPick the right category per line and attach the reason code to every exemption or zero rate. For education and health, attach the buyer's national ID.
- BR-KSA-17BR-KSA-56BR-55
Credit and debit notes
A credit note (381) or debit note (383) needs the reason for issuing it and a reference to the original invoice number.
Usual cause: A note issued with no reason text, or with no original invoice number.FixWrite the reason and reference the original invoice number. Our article on the two notes, at the bottom of this page, covers the difference.
- BR-KSA-03BR-KSA-33BR-KSA-34BR-KSA-61BR-KSA-26
Counter, UUID and hash chain
Each document has a unique UUID, a counter (ICV) of digits only, and the previous document hash (PIH) as base64 SHA-256. The first document uses a fixed starting hash.
Usual cause: A document reusing a counter or UUID used before, or a previous hash computed on a document other than the one generated just before.FixGive every document, resubmissions included, a new UUID and counter, and a previous hash equal to the hash of the last document generated before it.
- BR-KSA-27BR-KSA-28BR-KSA-29BR-KSA-30BR-KSA-60
QR code, signature and stamp
The QR code is required, base64-encoded. The signature block carries exact text values, and a simplified invoice needs your own cryptographic stamp.
Usual cause: A signature with identifiers or a method other than those specified, a simplified invoice with no stamp, or a signature made with an invalid certificate.FixUse the signature values the standard specifies, character for character, and complete onboarding to get a valid CSID certificate before sending.
- BR-KSA-04BR-KSA-70BR-KSA-15BR-KSA-35BR-KSA-36BR-KSA-68
Dates, times and currency
The issue date cannot be after today, and the issue time is required as hh:mm:ss. A tax invoice also needs a supply date and a tax currency code.
Usual cause: An issue date after today, a missing issue time or supply date, or a supply end date earlier than the supply date.FixGenerate the issue date and time from an accurate clock at creation, and fill the supply date and tax currency on every tax invoice.
- BR-KSA-05BR-KSA-06BR-KSA-07BR-KSA-31
Invoice type and transaction code
The invoice type code comes from an approved set. The 7-digit transaction code follows NNPNESB: type, third party, nominal, export, summary, self-billed.
Usual cause: A wrong value in one digit of the transaction code, self-billing on an export invoice, or a simplified invoice with an option it does not accept.FixCheck the seven transaction-code digits against the document type, and for a simplified invoice use only the options accepted for it.
ZATCA treats some errors as warnings without rejecting the document (exception handling). Check in the response whether the rule came back as an error or a warning.
Source: XML Implementation Standard, section 13 (invoice rules)
After a rejection: what to do and what not to do
A summary of ZATCA's own FAQ on resubmitting a rejected document.
- 1
Read the whole platform response
The response lists every error and warning with its message. Do not resubmit before you know which rule failed.
- 2
Fix the cause at the source
Correct the document data or the organization settings. The counter and hash of the rejected document are never changed.
- 3
Send a new document
Resubmit as a new document with a new UUID, counter, hash and timestamp. ZATCA's FAQ also allows cancelling the invoice by credit note and issuing a new one.
- 4
Point the previous hash at the last document generated
The previous hash is the hash of the document generated just before it, even if that one was rejected, because the platform records rejected hashes.
- 5
The date, for the two invoice types
For an uncleared standard (B2B) invoice the new invoice gets an updated date. A simplified invoice keeps the original transaction date, and no second invoice goes to the customer.
Test before sending with ZATCA's tools: the Compliance and Enablement Toolbox (SDK or web validator) and the integration sandbox. Source: Detailed Technical Guidelines, outcomes and FAQ
What Snad does when ZATCA responds
For every document it sends, Snad keeps the attempt history and ZATCA's responses to each attempt.
In Snad
- Shows ZATCA's response to each attempt as it arrived: errors, warnings and notices, with the response status code.
- Checks the VAT number, organization currency and country, and certificate validity before sending, and writes the reason and how to fix it.
- Groups failures under a “Failed invoices” filter, marks documents that used up their attempts as “Permanently failed”, and retries the failed ones only.
- Tells you when the national address or commercial registration is incomplete, since ZATCA attaches a warning to every invoice until it is.
- Lets you download the XML and PDF/A-3 of each document.
Not in Snad
- Shows ZATCA's message as it came and does not explain the rule ID in it. Use the categories on this page for its meaning.
Related pages and tools
E-invoicing in Snad, the document tools and our article on the two notes.
- E-invoicing and ZATCA requirementsPhases, waves and the difference between clearance and reporting
- Wave 25: who is covered and by when?Check whether your organization is in the wave
- Tax Invoice GeneratorA tax invoice as a PDF with a QR code
- Credit Note GeneratorA credit note referencing the original invoice
- Credit notes vs debit notes: a ZATCA compliance guideWhen each note is issued and the data it needs
Questions about rejected invoices
Not seeing your question? Contact us
Link your invoices with Fatoora and review every response in Snad
Fatoora linkage is included in the Basic and Pro plans. Start on the free Starter plan until you need linkage.
Starter stays free · 7-day trial of any paid plan, no card