ZATCA e-invoicing errors explained, with fixes

By Mohammed Nagieeb, the engineer who built Matheel's engine · Updated October 24, 2026

These are the errors and warnings we actually hit while building Matheel's engine and running it against ZATCA's gateways. For each code: what it means, why it shows up, and how to fix it. If you use Matheel, most of them are handled before the invoice reaches ZATCA.

Counter and hash (the chain)

BR-KSA-33 and BR-KSA-34 · Invoice counter (ICV)

Meaning: every invoice must carry the invoice counter (ICV) in a cac:AdditionalDocumentReference with ID ICV, digits only. Missing it is an error and the invoice is rejected.

Fix: keep one counter per device that goes up by one per invoice and is never reset. Advance it once ZATCA accepts the invoice; fix a rejected invoice and resend it with the same counter. BR-KSA-33 details

BR-KSA-61 and BR-KSA-26 · Previous invoice hash (PIH)

Each invoice carries the previous one's hash (base64 SHA-256). The first invoice on a device uses the initial value published in ZATCA's SDK; after that, store invoice_hash from every accepted response. BR-KSA-61 details

The hash breaks after signing

Any change to the XML after the hash is computed, even re-indenting, makes the hash wrong. Hash last and never touch the document afterwards.

Seller and buyer

BR-KSA-09 and BR-KSA-37 · Seller address

The seller address needs street, building number, postal code, city, district and country code (BR-KSA-09), and the building number must be exactly 4 digits (BR-KSA-37). BR-KSA-09 · BR-KSA-37

BR-KSA-08 · Seller identification

The seller ID (BT-29) appears once with one of the schemes CRN, MOM, MLS, SAG, OTH or 700, alphanumeric only. Most common: the commercial registration with schemeID="CRN". Details

BR-KSA-42, BR-KSA-81 and BR-KSA-44 · Buyer details on standard invoices

A standard (B2B) tax invoice and its notes need the buyer name (BR-KSA-42). A buyer without a VAT number needs another buyer ID (BR-KSA-81); a buyer VAT number must be 15 digits starting and ending with 3 (BR-KSA-44). Simplified invoices need none of this. BR-KSA-42 · BR-KSA-81 · BR-KSA-44

BR-KSA-10 · Buyer address

On standard tax invoices the buyer address needs street, city and country code. ZATCA's message mentions non-Saudi buyers, but the check the SDK actually runs applies to every standard invoice. It does not apply to simplified invoices. Details

Credit and debit notes

BR-KSA-56 and BR-KSA-17 · Reference and reason

Credit (381) and debit (383) notes must reference the original invoice (BillingReference, BR-KSA-56) and state why they were issued (BR-KSA-17, an error that rejects the note). Keep amounts positive: the document type sets the direction. BR-KSA-56 · BR-KSA-17

Totals and lines

BR-CO-10, BR-CO-13 and BR-CO-15 · Totals

The sum of line net amounts equals the lines (BR-CO-10); the total without VAT equals the lines minus document allowances plus document charges (BR-CO-13); the total with VAT equals the total without VAT plus VAT (BR-CO-15, an error). BR-CO-15 details

BR-KSA-EN16931-11 and BR-KSA-51 · Line arithmetic

Line net amount = quantity × (price / base quantity) + line charges − line allowances, and the line amount with VAT = line net amount + line VAT. Details

BR-16, BR-25 and BR-26 · Lines

An invoice needs at least one line (BR-16), and each line needs an item name (BR-25) and a net price (BR-26). If your software only sends a total, make one line carrying the full amount.

BR-KSA-19 · Charge reason

Every document-level charge needs a reason code. Details

BR-KSA-EN16931-08 and BR-CO-18 · Tax total

Only one TaxTotal may carry the tax subtotals (TaxSubtotal), and the invoice needs at least one VAT breakdown (BR-CO-18). Details

VAT and exemptions

BR-KSA-CL-04 and BR-KSA-24 · Exemption reason codes

Zero-rated (Z) and exempt (E) lines need a reason code from ZATCA's list (VATEX-SA-…, BR-KSA-CL-04); out-of-scope (O) needs an exception reason code (BR-KSA-24), which is VATEX-SA-OOS. Watch out: the older VAT-OOS-SA triggers a CL-04 warning; we checked both against the SDK rules. BR-KSA-CL-04 · BR-KSA-24

BR-KSA-68 and BR-KSA-EN16931-02 · Tax currency

TaxCurrencyCode must be present (BR-KSA-68) and be SAR (BR-KSA-EN16931-02); both are errors. Details

BR-KSA-16 · Payment means code

If the invoice has a payment means (BT-81), its code must come from ZATCA's subset of UNTDID 4461 (for example 10 cash, 30 credit transfer, 48 bank card). Details

Timing and field length

BR-KSA-98 · The 24-hour window

Simplified invoices must be reported to ZATCA within 24 hours of issue. Details

BR-KSA-F-06 · Field length

A family of rules setting the length limits of each field. Empty or over-long values raise a warning. All limits in one table

Things with no code that still stop you

• Arabic disappears from the CSR: openssl silently drops non-Latin subject fields and the ones after them, and ZATCA rejects the CSR. Write the CSR fields in a way that keeps Arabic intact.
• HTTP 303 (clearance switched off): some accounts answer 303 on the clearance path; fall back to reporting.
• "Submitted before" (406) during compliance checks: each check counts once per certificate, so resubmitting returns 406. Treat it as passed and move on.
• Passing the sandbox is half the way: the production CSID is issued in the taxpayer's own name with an OTP from their Fatoora account, so plan your first customer's onboarding early.

All rules and explanations are open data (JSON) on GitHub.

Got a response from ZATCA? Paste it into the response reader and every code in it is explained.

See also where ZATCA's rules differ from their own text: 6 tested findings.

All ZATCA rules

Saudi rules (BR-KSA)

• BR-CL-KSA-14 · The QR code value must be 1 to 1000 characters long
• BR-CUSTOM-VALIDATION-01 · Seller and buyer VAT numbers must not be the same
• BR-KSA-03 · Every invoice needs a UUID
• BR-KSA-04 · Issue date must not be in the future
• BR-KSA-05 · Invoice type code must be 388, 383, 381 or 386
• BR-KSA-06 · Invoice transaction code (name attribute) must follow NNPNESB
• BR-KSA-07 · Export invoices cannot be self-billed
• BR-KSA-08 · Seller ID needs a valid scheme (CRN, MOM, MLS, SAG, OTH, 700)
• BR-KSA-09 · Seller address: street, building, postcode, city, district, country
• BR-KSA-10 · Standard invoices need buyer street, city and country code
• BR-KSA-11 · 'Not subject to VAT' (O) lines must have a VAT rate of 0 if given
• BR-KSA-12 · 'Not subject to VAT' (O) allowances must have a VAT rate of 0 if given
• BR-KSA-13 · 'Not subject to VAT' (O) charges must have a VAT rate of 0 if given
• BR-KSA-14 · Buyer ID must use an allowed scheme ID
• BR-KSA-15 · Standard tax invoices (388) need a supply date
• BR-KSA-16 · Payment means code must be a valid UNTDID 4461 code
• BR-KSA-17 · Credit and debit notes need a reason for issuing
• BR-KSA-18 · VAT category code must be S, Z, E or O
• BR-KSA-19 · Each document-level charge needs a reason code
• BR-KSA-20 · Each invoice line charge needs a reason code
• BR-KSA-21 · Each document-level charge needs a charge reason text (BT-104)
• BR-KSA-22 · Each invoice line charge needs a charge reason text (BT-144)
• BR-KSA-23 · VAT-exempt (E) breakdown needs an exemption reason code (BT-121)
• BR-KSA-24 · Not-subject-to-VAT (O) breakdown needs a reason code (BT-121)
• BR-KSA-25 · Simplified invoice with EDU/HEA exemption needs the buyer name
• BR-KSA-26 · Previous invoice hash (PIH) attachment must be filled, text/plain
• BR-KSA-27 · Simplified invoices must carry a QR code (KSA-14)
• BR-KSA-28 · Signature information ID must be ...ubl:signature:1
• BR-KSA-29 · Signature ID and referenced signature ID must be ...signature:Invoice
• BR-KSA-30 · Signature method must be the enveloped XAdES URN
• BR-KSA-31 · Simplified invoices cannot be self-billed (KSA-2 position 7 = 0)
• BR-KSA-33 · Every invoice needs an invoice counter value (ICV, KSA-16)
• BR-KSA-34 · Invoice counter value (ICV, KSA-16) must contain only digits
• BR-KSA-35 · A supply end date (KSA-24) requires a supply date (KSA-5)
• BR-KSA-36 · Supply end date (KSA-24) must not be before supply date (KSA-5)
• BR-KSA-37 · Seller building number must be exactly 4 digits
• BR-KSA-39 · Seller VAT registration number (BT-31) is required
• BR-KSA-40 · Seller VAT number (BT-31): 15 digits, starting and ending with 3
• BR-KSA-42 · Standard tax invoices and their notes need the buyer name (BT-44)
• BR-KSA-44 · Buyer VAT number (BT-48): 15 digits, starting and ending with 3
• BR-KSA-49 · EDU/HEA exemption requires buyer national ID (BT-46, scheme NAT)
• BR-KSA-51 · Line amount with VAT (KSA-12) = line net amount + line VAT
• BR-KSA-52 · Each line needs a line VAT amount (KSA-11) on standard invoices
• BR-KSA-53 · Each line needs a line amount with VAT (KSA-12) on standard invoices
• BR-KSA-56 · Credit and debit notes must reference the original invoice (BT-25)
• BR-KSA-60 · Simplified invoices must include the cac:Signature block (KSA-15)
• BR-KSA-61 · Every invoice needs the previous invoice hash (PIH, KSA-13)
• BR-KSA-63 · Saudi buyer needs a full national address on standard invoices
• BR-KSA-66 · Seller postal code (BT-38) must be exactly 5 digits
• BR-KSA-67 · Saudi buyer postal code (BT-53) must be 5 digits
• BR-KSA-68 · Every invoice needs a tax currency code (BT-6)
• BR-KSA-69 · Zero-rated (Z) VAT breakdown needs a reason code (BT-121)
• BR-KSA-70 · Invoice issue time (KSA-25) is required as hh:mm:ss or hh:mm:ssZ
• BR-KSA-71 · Simplified summary invoices need the buyer name
• BR-KSA-72 · Simplified summary invoices need supply start and end dates
• BR-KSA-73 · Prepaid amount (BT-113) requires full prepayment reference on lines
• BR-KSA-74 · Prepayment document type code (KSA-30) on lines must be 386
• BR-KSA-75 · Prepayment lines need taxable amount, tax amount, category and rate
• BR-KSA-76 · Zero-rated (Z) prepayment line VAT rate must be 0
• BR-KSA-77 · Exempt (E) prepayment line VAT rate must be 0
• BR-KSA-78 · Not-subject (O) prepayment line VAT rate must be 0
• BR-KSA-79 · Line VAT breakdown: tax amount = taxable amount x rate / 100
• BR-KSA-80 · Prepaid amount must equal prepayment taxable plus tax amounts
• BR-KSA-81 · Standard invoice without buyer VAT number needs another buyer ID
• BR-KSA-82 · Prepayment lines must carry zero line amounts
• BR-KSA-83 · Exemption reason code in the VAT breakdown needs a reason text
• BR-KSA-84 · Standard-rated (S) VAT rate must be 15 or 5
• BR-KSA-85 · Buyer phone must start with 0 or + followed by 4 to 15 digits
• BR-KSA-86 · Buyer email should follow the XXX@YYY.ZZ format
• BR-KSA-87 · Tax exchange rate needs source currency, target currency and rate
• BR-KSA-88 · Exchange-rate source currency must equal the invoice currency
• BR-KSA-89 · Exchange-rate target currency must equal the tax currency
• BR-KSA-90 · Tax exchange rate may be at most 14 characters long
• BR-KSA-92 · B2G invoices must include a contract ID
• BR-KSA-93 · Zero-rated (Z) line VAT breakdown needs an exemption reason code
• BR-KSA-94 · Exempt (E) line VAT breakdown needs an exemption reason code
• BR-KSA-95 · Not-subject (O) line VAT breakdown needs an exemption reason code
• BR-KSA-96 · Line exemption reason code needs a reason text
• BR-KSA-97 · Non-SAR invoice: SAR VAT total must differ from the VAT total
• BR-KSA-98 · Simplified invoices should be submitted within 24 hours
• BR-KSA-99 · Buyer VAT number must not be empty when the element is present
• BR-KSA-CL-01 · Invoice currency code must be a valid ISO 4217 code
• BR-KSA-CL-02 · Every amount's currencyID must match the invoice currency
• BR-KSA-CL-03 · Attachment mimeCode must be one of the allowed types
• BR-KSA-CL-04 · VAT exemption reason code must fit the VAT category
• BR-KSA-CL-06 · Charge reason codes must come from UNTDID 7161
• BR-KSA-CL-07 · Prepayment exemption reason code must fit its VAT category
• BR-KSA-DEC-01 · Document allowance percentage must be 0-100 with up to 2 decimals
• BR-KSA-DEC-02 · VAT rates must be 0-100 with at most two decimals
• BR-KSA-DEC-03 · Line VAT amount may have at most two decimals
• BR-KSA-DEC-04 · Line amount with VAT may have at most two decimals
• BR-KSA-DEC-06 · Prepayment taxable and tax amounts may have at most two decimals
• BR-KSA-EN16931-01 · Business process (ProfileID) must be reporting:1.0
• BR-KSA-EN16931-02 · VAT accounting currency (TaxCurrencyCode) must be SAR
• BR-KSA-EN16931-03 · Allowance/charge amount must equal base amount × percentage / 100
• BR-KSA-EN16931-04 · An allowance/charge percentage needs a base amount
• BR-KSA-EN16931-05 · An allowance/charge base amount needs a percentage
• BR-KSA-EN16931-06 · Price-level allowance/charge must have ChargeIndicator false
• BR-KSA-EN16931-07 · Net item price must equal gross price minus price discount
• BR-KSA-EN16931-08 · Exactly one TaxTotal with tax subtotals per invoice
• BR-KSA-EN16931-09 · With a tax currency code, add one TaxTotal without subtotals
• BR-KSA-EN16931-11 · Line net amount = quantity × net price ± line charges/allowances
• BR-KSA-EN16931-12 · Item price base quantity must be greater than zero

Core invoice rules (EN 16931)

• BR-02 · Every invoice needs an invoice number (BT-1)
• BR-03 · Every invoice needs an issue date (BT-2)
• BR-04 · Every invoice needs an invoice type code (BT-3)
• BR-05 · Every invoice needs a currency code (BT-5)
• BR-06 · The seller's legal name (BT-27) must be present
• BR-08 · The seller's postal address (BG-5) must be present
• BR-09 · The seller address must include a country code (BT-40)
• BR-13 · The invoice total without VAT (BT-109) must be present
• BR-14 · The invoice total with VAT (BT-112) must be present
• BR-15 · The amount due for payment (BT-115) must be present
• BR-16 · Every invoice needs at least one invoice line (BG-25)
• BR-21 · Each invoice line needs a line identifier (BT-126)
• BR-22 · Each invoice line needs an invoiced quantity (BT-129)
• BR-24 · Each invoice line needs a line net amount (BT-131)
• BR-25 · Each invoice line needs an item name (BT-153)
• BR-26 · Each invoice line needs an item net price (BT-146)
• BR-31 · Each document-level allowance needs an amount (BT-92)
• BR-32 · Each document-level allowance needs a VAT category code (BT-95)
• BR-36 · Each document-level charge needs an amount (BT-99)
• BR-37 · Each document-level charge needs a VAT category code (BT-102)
• BR-41 · Each line-level allowance needs an amount (BT-136)
• BR-43 · Each line-level charge needs an amount (BT-141)
• BR-45 · Each VAT breakdown needs a taxable amount (BT-116)
• BR-46 · Each VAT breakdown needs a VAT amount (BT-117)
• BR-47 · Each VAT breakdown needs a VAT category code (BT-118)
• BR-48 · Each VAT breakdown needs a VAT rate (BT-119) unless category is O
• BR-49 · Payment means must state a payment means code (BT-81)
• BR-52 · Each additional document reference needs an ID (BT-122)
• BR-53 · With a tax currency (BT-6), give the VAT total in it (BT-111)
• BR-54 · Each item attribute needs a name (BT-160) and a value (BT-161)
• BR-55 · A billing reference must give the preceding invoice number (BT-25)
• BR-DEC · Decimal places

Totals and calculations (BR-CO)

• BR-CO-04 · Every invoice line needs a VAT category code
• BR-CO-10 · Total line amount must equal the sum of all line net amounts
• BR-CO-11 · Allowance total must equal the sum of document-level allowances
• BR-CO-12 · Charge total must equal the sum of document-level charges
• BR-CO-13 · Total without VAT = line amounts - allowances + charges
• BR-CO-14 · Total VAT must equal the sum of the VAT breakdown amounts
• BR-CO-15 · Total with VAT must equal total without VAT plus total VAT
• BR-CO-16 · Amount due = total with VAT - prepaid amount + rounding amount
• BR-CO-17 · VAT amount per category must equal taxable amount x rate
• BR-CO-18 · Every invoice needs at least one VAT breakdown

VAT categories (S, Z, E, O)

• BR-E-01 · Exempt (E) items need an 'E' VAT breakdown
• BR-E-05 · Exempt (E) invoice lines must have a VAT rate of 0
• BR-E-06 · Exempt (E) document allowances must have a VAT rate of 0
• BR-E-07 · Exempt (E) document charges must have a VAT rate of 0
• BR-E-08 · Exempt (E) taxable amount must match the exempt lines and adjustments
• BR-E-09 · VAT amount in an exempt (E) breakdown must be 0
• BR-O-01 · 'Not subject to VAT' (O) items need an O VAT breakdown
• BR-O-08 · 'Not subject to VAT' (O) taxable amount must match its lines
• BR-O-09 · 'Not subject to VAT' (O) breakdown tax amount must be 0
• BR-S-01 · Standard-rated (S) items need an S VAT breakdown
• BR-S-05 · Standard-rated (S) line VAT rate must be above zero
• BR-S-06 · Standard-rated (S) document allowance VAT rate must be above zero
• BR-S-07 · Standard-rated (S) document charge VAT rate must be above zero
• BR-S-08 · Standard-rated (S) taxable amount must match its lines
• BR-S-09 · Standard-rated (S) tax amount = taxable amount × rate / 100
• BR-S-10 · Standard-rated (S) VAT breakdown must not have an exemption reason
• BR-Z-01 · Zero-rated (Z) items need a Z VAT breakdown
• BR-Z-05 · Zero-rated (Z) line VAT rate must be 0
• BR-Z-06 · Zero-rated (Z) document allowance VAT rate must be 0
• BR-Z-07 · Zero-rated (Z) document charge VAT rate must be 0
• BR-Z-08 · Zero-rated (Z) taxable amount must match its lines
• BR-Z-09 · Zero-rated (Z) breakdown tax amount must be 0

Code lists (BR-CL)

• BR-CL-01 · Invoice type code must be a valid UNTDID 1001 code
• BR-CL-03 · Amount currencyID must be an ISO 4217 alpha-3 code
• BR-CL-04 · Invoice currency code must be an ISO 4217 alpha-3 code
• BR-CL-05 · Tax currency code must be an ISO 4217 alpha-3 code
• BR-CL-14 · Country codes must be ISO 3166-1 alpha-2 codes
• BR-CL-16 · Payment means code must be from the UNCL4461 list
• BR-CL-18 · Tax category codes must come from the UNCL5305 code list

Field formats (BR-KSA-F)

• BR-KSA-F-01 · Dates must use the YYYY-MM-DD format
• BR-KSA-F-02 · Allowance/charge indicator must be 'false' or 'true'
• BR-KSA-F-04 · Invoice amounts and quantities must not be negative
• BR-KSA-F-05 · Prepayment issue time must be a valid hh:mm:ss time
• BR-KSA-F-07 · Buyer TIN must be 10 digits starting with 3
• BR-KSA-F-08 · Seller/buyer CRN must be exactly 10 digits
• BR-KSA-F-09 · Seller/buyer '700' number must be 10 digits starting with 7
• BR-KSA-F-10 · Buyer national ID (NAT) must be 10 digits starting with 1
• BR-KSA-F-11 · Buyer Iqama number (IQA) must be 10 digits starting with 2
• BR-KSA-F-12 · Seller/buyer ID schemeID must not contain extra spaces
• BR-KSA-F-13 · Seller/buyer ID must not be a placeholder digit sequence
• BR-KSA-F-06 · Field length limits