ZATCA error codes such as BR-KSA-40 come back with a short message when FATOORA rejects an invoice in Saudi Arabia or accepts it with a warning. Type the code in the search box above or paste the whole response: each message shows its official text, whether it is an error or a warning, the XML field behind it, the usual causes and a fix checklist you can tick off. Every message also downloads as a one-page PDF fix sheet to hand to your developer or solution provider.
How to look up a ZATCA error code
Search reads three kinds of input: the code alone in any spelling (BR-KSA-40 or br ksa 40), the full platform response with all its codes, or a word from the message. One code opens its explanation straight away; several codes are listed with errors first, because errors are what block the invoice now. Codes in your text that are not explained here yet are named under the result count, so none gets lost.
The More filters switch narrows the list by level and invoice type, and the copy-link button inside each explanation gives you a link that opens that message on its own.
Errors and warnings: clearance vs reporting
Standard tax invoices go through clearance: you submit them before handing them to the buyer, and a rejected one is not a valid invoice. Simplified invoices go through reporting: the customer gets them at once and you report them within 24 hours of issue. Either way the response holds one of two outcomes: at least one error, so the invoice is rejected and must be corrected and resubmitted, or warnings only, so it is accepted with them.
The level shown next to each code comes from the validation rule files in the software development kit (SDK) that ZATCA publishes, the same files the platform validates with. If the platform response shows a different level for a code, the response wins, because ZATCA updates the rules between releases.
Reading a FATOORA rejection message
Official messages name the field by its data-model ID: BT for fields inherited from the European e-invoicing standard (BT-31 is the seller VAT number) and KSA for local fields (KSA-16 is the invoice counter). That is why each explanation here gives the XML path, so you can search the file for it. Codes come in three families: BR and BR-CO from the European rules, and BR-KSA from ZATCA's own rules. Some messages have no BR code because they come from other checks: schema, QR code, signature and the hash chain.
To read the QR code or the XML file itself and check its format and amounts, use the e-invoice reader, then come back here with the message code.
The most common FATOORA rejection codes
| Code | What is wrong | Check first |
|---|---|---|
| BR-KSA-40 | Seller VAT number in the wrong format | 15 digits, first and last digit 3 |
| BR-KSA-33 | Invoice counter (ICV) | The counter after a system upgrade or move |
| BR-KSA-70 | Issue time format | Fractions of a second and time zone offset |
| BR-CO-15 | Total including VAT | A discount applied after VAT, and rounding |
| BR-KSA-84 | Rate for the standard category | A zero-rated item coded as category S |
| BR-KSA-17 | Reason on a credit note | The InstructionNote field |
| invoiceTotal | QR total does not match the invoice | Code generated before the last edit |
The warnings seen most on standard tax invoices are about missing buyer details: the name (BR-KSA-42), the full national address (BR-KSA-63), and another identifier when the buyer has no VAT number (BR-KSA-81).
Common mistakes when fixing a rejection
- Editing the XML after signing. Any change, even whitespace, alters the hash and triggers signature and QR errors. Fix the data in your system and sign again.
- Resubmitting with the old counter and previous hash. Every submission is a new document in the device chain, with the next counter and the hash of the last accepted invoice.
- Ignoring warnings because the invoice went through. They repeat on every invoice and may turn into rejections when the rules are updated.
- Fixing only the first message. A response can carry several; paste the whole response here to see all of them.
- Changing the invoice date to avoid the late-reporting warning. The date stays the real issue date.
What to do after you fix the message
If the invoice was rejected, submit the same invoice again after the correction and confirm the response has no errors. Then look for the cause in the settings rather than in that invoice alone: branch details, the customer record, the invoice template and the scheduled submission job, so it does not come back on the next invoice. If the message concerns how the solution is built (hashing, signing or element order), send the PDF fix sheet to your solution provider with the response text exactly as you received it. To find your business's mandatory integration date, use the ZATCA wave checker.
When rejections show up every day
At Microtec we build accounting software (ERP) that brings sales, purchasing, inventory, finance and HR together, and our solutions are approved by ZATCA. If invoices come out of several systems and each one gets fixed separately, try keeping invoices, customer records and branch details in one place.