Errors and warnings: rejected or accepted
Every invoice, credit note and debit note you send to Fatoora comes back with one of three outcomes. ZATCA defines them plainly: an error is a validation failure on a rejected document, a warning is a validation failure on an accepted document, and a document with even one error is rejected entirely.
Warnings are not a free pass. ZATCA says warnings are temporarily accepted and might become rejections in the future, and that taxpayers who keep sending them may be investigated. Its own example of a minor mistake that is accepted with warnings is a missing building number in the address. Fix warnings on the next invoice; fix errors before anything else.
Fatoora responses and what to do
| Response | What it means | What to do |
| 200 | Accepted: cleared (standard) or reported (simplified) | Nothing |
| 202 | Accepted with warnings | Pass the warnings to whoever maintains your invoicing system and fix the data before the next invoice |
| 400 | Rejected: at least one error | Read the error codes, correct the data and submit a new document |
| 401 | Unauthorized | Check the authentication certificate (CSID) and secret, then resubmit |
| 303 | Clearance switched off | Submit the standard invoice through the reporting API instead |
| 429, 500, 503, 504 | ZATCA did not receive the invoice | Send the same invoice again |
How to read a ZATCA error code
Fatoora checks each document in layers: the UBL 2.1 schema, then a subset of the European EN 16931 rules, then the KSA rules, and for simplified (B2C) documents the QR code and your cryptographic stamp. Where a KSA rule and an EN 16931 rule cover the same point, the KSA rule wins.
The code tells you which layer failed. BR- and BR-CO- codes are EN 16931 rules (BR-CO are the arithmetic checks). BR-KSA- codes are Saudi rules, with families for decimals (BR-KSA-DEC), code lists (BR-KSA-CL), formats (BR-KSA-F) and Saudi changes to EN 16931 (BR-KSA-EN16931). The message names the field by its term number, such as BT-48 for the buyer VAT number or KSA-2 for the transaction code.
Nearly every error traces back to master data: the customer record, your company profile or a tax rate. Fix it there once and every later invoice passes.
Buyer and seller data errors
Frequent BR-KSA errors in party data
| Rule | What it means | How to fix |
| BR-KSA-44 | Buyer VAT number is not 15 digits starting and ending with 3 | Correct the VAT number on the customer record, digits only |
| BR-KSA-46 | An export invoice carries a buyer VAT number | Leave the VAT number off customers abroad; give another ID instead |
| BR-KSA-81 | Standard invoice with no buyer VAT number and no other buyer ID | Add another ID such as the CR number, national ID or Iqama number |
| BR-KSA-14 | Other buyer ID has a wrong scheme or characters | Use TIN, CRN, MOM, MLS, 700, SAG, NAT, GCC, IQA, PAS or OTH, with letters and digits only |
| BR-KSA-42 | Buyer name missing on a standard invoice | Fill in the customer legal name |
| BR-KSA-63 | Saudi buyer address incomplete | Fill street, building number, postal code, city and district from the national address |
| BR-KSA-67 | Saudi buyer postal code is not 5 digits | Correct the postal code on the customer record |
| BR-KSA-10 | Buyer address incomplete on a standard invoice | A non-Saudi buyer needs at least street, city and country |
| BR-KSA-09 | Seller address incomplete | Fill street, building number, postal code, city and district on your company profile |
| BR-KSA-37 / BR-KSA-66 | Seller building number not 4 digits, or postal code not 5 digits | Copy both exactly from your national address |
| BR-KSA-40 | Seller VAT number is not 15 digits starting and ending with 3 | Use the VAT number from your ZATCA registration certificate |
| BR-KSA-08 | Seller ID missing, repeated or with a wrong scheme | Give one ID: CRN, MOM, MLS, 700, SAG or OTH, in that order of priority |
Invoice type code and transaction flags (BR-KSA-05, BR-KSA-06)
Two fields decide how ZATCA treats a document. The invoice type code (BR-KSA-05) must be 388 for a tax invoice, 381 for a credit note, 383 for a debit note or 386 for a prepayment invoice. The transaction code (KSA-2, checked by BR-KSA-06) is a seven-digit string of flags written into the same element.
- BR-KSA-07: an export invoice (position 5 = 1) cannot also be self-billed (position 7 = 1)
- BR-KSA-31: a simplified invoice may only set the third-party, nominal and summary flags
- BR-KSA-17: a credit or debit note must give the reason it was issued (KSA-10)
- BR-KSA-56: a credit or debit note must reference the original invoice number (BT-25)
- BR-KSA-15: a standard tax invoice must carry the supply date (KSA-5)
- BR-KSA-71 / BR-KSA-72: a simplified summary invoice needs the buyer name and both supply dates
Reading the transaction code (KSA-2)
- Positions 1–2: 01 standard tax invoice (cleared) or 02 simplified tax invoice (reported)
- Position 3: third-party invoice · position 4: nominal supply · position 5: export
- Position 6: summary invoice · position 7: self-billed invoice (1 = yes, 0 = no)
- Standard tax invoice, no flags: 0100000 with type code 388
- Simplified tax invoice, no flags: 0200000 with type code 388
Hash chain, counter, QR and stamp errors
Every document carries the hash of the document before it (the previous invoice hash, PIH) and an invoice counter value (ICV). ZATCA requires one sequence per e-invoicing unit, shared by standard and simplified documents, and records the hash of rejected documents too. So the PIH must point to the last document your unit generated, not the last one ZATCA accepted. An invoice issued outside the integrated system breaks the chain.
- BR-KSA-61: every document must carry the previous invoice hash
- BR-KSA-26: the PIH must be a base64-encoded SHA-256 hash computed the way the standard describes; for the very first document it is the hash of the character 0
- BR-KSA-33 / BR-KSA-34: every document needs an invoice counter value made of digits only; ZATCA adds that a counter value is never reused
- BR-KSA-03: the UUID may contain only letters, digits and dashes
- BR-KSA-27: the document must contain a QR code encoded in base64
- BR-KSA-60: simplified documents must carry your cryptographic stamp, because ZATCA does not stamp them
- BR-KSA-28, BR-KSA-29, BR-KSA-30: the signature block must use the exact identifiers and signature method the standard gives
Totals, rounding and decimals
The arithmetic rules reject an invoice whose numbers do not add up. Line net amounts must sum to the invoice line total (BR-CO-10); the total without VAT is that sum less document allowances plus charges (BR-CO-13); the VAT total must equal the sum of the VAT breakdown (BR-CO-14); and the total with VAT must equal the total without VAT plus VAT (BR-CO-15).
Most failures are rounding. Each VAT category amount must equal its taxable amount times the rate, rounded to two decimals (BR-CO-17, and BR-S-09 for standard-rated lines). Pick one rounding method and keep it on every line and every invoice.
- BR-KSA-51: on each line, the amount with VAT must equal the line net amount plus the line VAT
- BR-KSA-EN16931-11: the line net amount must equal quantity × net price, plus line charges, minus line allowances
- BR-KSA-DEC-02: VAT rates are numbers from 0.00 to 100.00 with at most two decimals, without the % sign
- BR-KSA-DEC-03 / BR-KSA-DEC-04: line VAT and line amount with VAT have at most two decimals
- BR-KSA-F-04: amounts and quantities must be positive; a return is a credit note, not a negative line
- BR-KSA-68 and BR-KSA-EN16931-02: the tax currency code must be present and must be SAR
Dates, times and VAT categories
- BR-KSA-04: the issue date cannot be later than the current date; check the clock and time zone of the device that issues invoices
- BR-KSA-70: the issue time is hh:mm:ss in Saudi time or hh:mm:ssZ in UTC; a UTC time without the Z is read as Saudi time
- BR-KSA-F-01: dates are written YYYY-MM-DD
- BR-KSA-36: a supply end date cannot be earlier than the supply date
- BR-KSA-18: the VAT category is S, Z, E or O, nothing else
- BR-KSA-69, BR-KSA-23, BR-KSA-24: zero-rated, exempt and out-of-scope amounts need an exemption reason code, taken from ZATCA's VATEX list (BR-KSA-CL-04) with its matching text (BR-KSA-83)
- BR-KSA-F-03 and BR-KSA-F-06: no empty elements, and every field within the character limits in the data dictionary
Certificate (CSID) and onboarding errors
These problems are not BR rules, but they stop every invoice. ZATCA states that invoices signed with an invalid certificate are rejected; the API answers 401 when the authentication certificate or secret is wrong.
- During onboarding, ZATCA lists the usual CSR errors: an OTP that is not six digits, an OTP generated for another VAT number, an expired OTP, an invalid VAT number and missing fields
- If a compliance check fails, the unit starts again with a new OTP and a new CSR
- The production CSID expires. Renew it before the expiry date; renewal revokes the old CSID and issues a new one
- An invoice cleared in the sandbox or simulation environment is a test. It is not a valid invoice to give a buyer
Fixing a rejected invoice the right way
- Standard invoice rejected: it is not a valid tax invoice and must not go to the buyer. Correct the data and submit it as a new document with its own UUID, counter value, hash and time stamp
- Simplified invoice rejected after issue: the customer already has it. Fix the cause and submit a corrected document for reporting; ZATCA does not expect you to reissue it to the customer
- Never edit a cleared invoice. Correct it with a credit or debit note that references it, which is itself cleared or reported
- Keep the chain: the new document's PIH is the hash of the document generated just before it, even if that was the rejected one
- Warnings: the document stands; fix the customer or company data so the next one is clean
- VAT still applies: ZATCA notes that a technical rejection does not cancel the sale, so the VAT is still due in your return
How ERP HRM Solution handles ZATCA responses
ERP HRM Solution connects to Fatoora with your own onboarding: you generate the OTP in the Fatoora portal, the software creates the CSR, runs ZATCA's compliance checks for your unit and receives your production CSID under Settings → E-invoicing. It is not listed in ZATCA's directory of e-invoicing solution providers.
A standard invoice is cleared when you issue it. If ZATCA rejects it, it stays a draft with each error code and message shown, so you fix the record and issue again; an invoice accepted with warnings is marked ZATCA cleared (warnings) with the warnings listed. Simplified invoices are reported in the background with retries, and the company is alerted when one is still unreported 20 hours after it was created. The hash chain moves on after a rejection, as ZATCA requires, and the software warns 30 days before the CSID expires.