ZATCA e-invoice error codes — a guide to rejections and fixes

Q: What is the difference between an error and a warning in the Authority's response?

An ERROR rejects the invoice, so it is never registered with the Authority and must be corrected and resubmitted. A WARNING does not block acceptance: the invoice is accepted as "accepted with warnings" and is legally valid, but it carries details worth fixing. Of 138 codes, 45 reject the invoice and 93 are warnings.

Q: Where do I find the error code in the Authority's response?

The Authority's response is a JSON object containing validationResults, which holds three lists: infoMessages, warningMessages and errorMessages. Each entry carries code, category and message. The code that rejects your invoice is the one inside errorMessages.

Q: My invoice was rejected — do I owe a fine?

A rejection is not itself a fine. But a simplified tax invoice must be reported within 24 hours of being issued, and a tax invoice needs clearance before you send it to the customer. If the deadline passes while the invoice is still rejected, you are in breach. Correct it and send it again the same day.

Q: Where did this list come from?

From the schematron validation rules published inside the Zakat, Tax and Customs Authority's e-invoicing SDK, version Java 238 R3.3.9. The message texts are reproduced verbatim as the Authority sends them in English; the explanations are ours.

Q: Is the list complete?

It covers everything the published validation rules state. We have also seen the live API return codes that are not in that release — we added those from real rejection responses we logged. If you receive a code that is not here, tell us and we will add it.

The codes that actually stop invoices

Each one has a page explaining what it means, why it happens and how to fix it.

The invoice chain: PIH and counter

The errors that break the invoice chain — and the hardest ones to understand.

BR-KSA-03 Rejects the invoice

Invoice UUID missing or invalid

KSA-1 is a machine identifier for the document, not the invoice number a customer reads. It is generated...

BR-KSA-26 Warning

Previous invoice hash (PIH) in the wrong format

The Authority rejects the invoice because the previous invoice hash is not a SHA-256 digest encoded in Ba...

BR-KSA-27 Warning

QR code (KSA-14) missing from a simplified document, or not in the expected form

The rule runs on simplified documents only, and looks for a document reference with the ID QR holding a n...

BR-KSA-33 Rejects the invoice

Invoice counter (ICV) missing or invalid

Counter KSA-16 is an increasing number that is never reset and never repeated. Why it gets rejected, and...

BR-KSA-34 Rejects the invoice

Invoice counter (ICV) holds something other than digits

Field KSA-16 takes digits and nothing else. Nearly everyone who receives this code has put the invoice nu...

BR-KSA-60 Warning

Cryptographic stamp (KSA-15) missing from a simplified document

A simplified invoice and its notes are stamped in your own system before they are handed to the customer...

BR-KSA-61 Warning

Previous invoice hash (PIH) missing from the invoice

Field KSA-13 is absent from the XML entirely. How this differs from BR-KSA-26, how to add the field, and...

Seller and buyer identity

VAT numbers and identifiers — what actually gets rejected most.

BR-CUSTOM-VALIDATION-01 Rejects the invoice

Seller VAT number identical to the buyer VAT number

The Authority rejects any invoice where the seller VAT number is the same as the buyer VAT number. The re...

BR-KSA-08 Warning

Seller identification (BT-29) missing, repeated or not alphanumeric

The commercial registration or licence an invoice carries for the seller is written once, under one of si...

BR-KSA-14 Rejects the invoice

Buyer identification (BT-46) missing or without its scheme

The rule applies only when the buyer is not registered for VAT. A registered buyer is identified by the V...

BR-KSA-39 Rejects the invoice

Seller VAT number missing

The invoice must carry the VAT number of the seller, or of the VAT group the seller belongs to. Its absen...

BR-KSA-40 Rejects the invoice

Seller VAT number invalid — 15 digits starting and ending with 3

The format rule for the Saudi VAT number, and the numbers people put in its place: the unified number, th...

BR-KSA-42 Warning

Tax invoice without a buyer name (BT-44)

A tax invoice and its credit and debit notes carry the buyer name in its own field. It is a warning, so t...

BR-KSA-44 Rejects the invoice

Buyer VAT number invalid on the invoice

When the buyer number is mandatory and when it must be left empty, and why a number that is present gets...

BR-KSA-49 Rejects the invoice

Education or healthcare exemption with no buyer national ID

The exemption reasons VATEX-SA-EDU and VATEX-SA-HEA are granted to a citizen, so a document carrying eith...

BR-KSA-81 Warning

Tax invoice to a buyer with neither a VAT number nor another ID (BT-46)

A tax invoice, or a note against one, whose buyer has no VAT number has to identify the buyer another way...

BR-KSA-F-13 Warning

Additional seller or buyer identifier holds an invalid value

Fields BT-29 and BT-46 carry an identifier other than the VAT number — a CR number, a licence, an ID. The...

National address

The six address elements and their lengths.

BR-KSA-09 Warning

Seller address incomplete on the invoice

The seller address must carry six complete elements. The two most often missing are the district and the...

BR-KSA-10 Warning

Buyer address incomplete — and the live message narrows it to a non-Saudi buyer

Three elements only: street, city and country code, on a tax invoice and its notes but not on a simplifie...

BR-KSA-37 Warning

Seller building number (KSA-17) is not 4 digits

A building number in the Saudi national address is four digits and nothing else. What most often produces...

BR-KSA-63 Warning

Saudi buyer address incomplete on the invoice

Once the buyer country code is SA, six elements of the buyer address become mandatory: street, building n...

BR-KSA-66 Warning

Seller postal code is not 5 digits

A Saudi postal code is exactly five digits. The most common cause of this error: writing the additional n...

BR-KSA-67 Warning

Buyer postal code is not 5 digits

The twin of BR-KSA-66 on the buyer side: if the buyer is in Saudi Arabia, the postal code is five digits....

BR-KSA-F-06-C23 Warning

Buyer street (BT-50) empty, or longer than the limit

A length rule, not a presence rule: the minimum is one character, and zero characters is what an element...

BR-KSA-F-06-C25 Warning

Buyer city (BT-52) empty, or longer than the limit

The city is the part everyone assumes is there, so an empty one almost always means a mapping fault rathe...

BR-KSA-F-06-C28 Warning

Buyer district (KSA-4) empty, or longer than the limit

The district is the part nobody holds in their data, so the temptation is to fill it with the city or wit...

Invoice type and transaction coding

The fields that decide what this document is in the first place.

BR-CO-15 Rejects the invoice

Invoice total with VAT is not the total without VAT plus the VAT

A European totals rule the Authority applies to every invoice: the invoice total with VAT (BT-112) must e...

BR-KSA-04 Rejects the invoice

Invoice date is in the future

The issue date of an invoice must not be later than the current date at the Authority. A past date is acc...

BR-KSA-05 Rejects the invoice

Invoice type (BT-3) holds a value that is not accepted

Four values are accepted: 388 invoice, 386 prepayment invoice, 381 credit note, 383 debit note. And why P...

BR-KSA-06 Rejects the invoice

Transaction type code (KSA-2) invalid — the NNPNESB structure

Seven digits that state the invoice type and the properties of the transaction. What each digit means, an...

BR-KSA-11 Rejects the invoice

Out-of-scope line carrying a non-zero rate

The category says the line is not subject to VAT, and the VAT rate on that line must therefore be zero wh...

BR-KSA-15 Warning

Tax invoice without a supply date (KSA-5)

A tax invoice carries two separate dates: the date it was issued and the supply date. The second is manda...

BR-KSA-16 Warning

Payment means code (BT-81) not in ZATCA's subset of UNTDID 4461

When an invoice states a payment means, the value must be a code from ZATCA's subset of UNTDID 4461, not...

BR-KSA-17 Rejects the invoice

Note issued with no reason

Every credit or debit note must carry the reason it was issued in a dedicated field. The original invoice...

BR-KSA-18 Rejects the invoice

Tax category code not accepted

The VAT category on a line is written as one of exactly four letters: S for the standard rate, Z for zero...

BR-KSA-23 Warning

Exempt category without an exemption reason code

Every VAT breakdown whose category is E, exempt, carries a reason code, and the exempt list holds only th...

BR-KSA-24 Warning

Out-of-scope category without a reason code

A VAT breakdown whose category is O, outside the scope of VAT, carries a reason code too, and it has exac...

BR-KSA-31 Rejects the invoice

Transaction type not allowed on a simplified invoice — export and self-billing

A simplified invoice and its notes may carry only three of the five transaction properties: third party,...

BR-KSA-51 Warning

Line amount with VAT (KSA-12) not equal to line net plus line VAT

The rule is a sum, not a derivation: the line amount with VAT equals the line net plus the line VAT amoun...

BR-KSA-52 Rejects the invoice

Line VAT amount (KSA-11) missing

The VAT on each line is a field of its own on a tax invoice and its credit and debit notes, and the total...

BR-KSA-53 Rejects the invoice

Line amount with VAT (KSA-12) missing

The twin of the line VAT amount, emitted from the same block. The UBL element it lives in is called Round...

BR-KSA-56 Warning

Credit or debit note with no reference to the original invoice

Every credit note (381) and debit note (383) must reference the number of the invoice it corrects. Why th...

BR-KSA-68 Rejects the invoice

Tax currency code (BT-6) missing

A Saudi invoice declares two currencies: the one you billed in, and the one the VAT is accounted in. The...

BR-KSA-69 Warning

Zero-rated category without an exemption reason code

Every VAT breakdown whose category is Z, zero-rated, carries a reason code from the Authority's list, suc...

BR-KSA-70 Rejects the invoice

Invoice issue time (KSA-25) missing or in the wrong format

The date and the time are two separate fields. A system that records only a date passes every date rule a...

BR-KSA-83 Warning

Exemption reason code without its reason text (BT-120)

A VAT breakdown that carries an exemption reason code carries its text as well. The test as the Authority...

BR-KSA-84 Rejects the invoice

VAT rate on a standard-rated item is neither 15 nor 5

Where the VAT category is S, standard rated, the only rates accepted are 15 and 5, in the five fields tha...

BR-KSA-85 Warning

Buyer phone number (BT-57) in an unaccepted format

A buyer phone number on the invoice starts with 0 or + and is followed by 4 to 15 digits and nothing else...

BR-KSA-86 Warning

Buyer email address (BT-58) in an unaccepted format

The buyer email on the invoice has a narrow pattern in the rule's text: letters, digits, dots and dashes...

BR-KSA-CL-01 Rejects the invoice

Invoice currency code (BT-5) is not an ISO 4217 code

The invoice currency is written as three letters from the ISO 4217 list — SAR — not as a currency symbol,...

BR-KSA-CL-02 Rejects the invoice

Mixed currency in the document — a currencyID attribute does not match the invoice currency

Every amount in the XML carries an attribute naming its currency, and all of them must repeat the invoice...

BR-KSA-CL-04 Warning

Exemption reason code (BT-121) not on the list for its category

When the VAT breakdown for a zero-rated, exempt or out-of-scope category carries an exemption reason code...

BR-KSA-DEC-02 Rejects the invoice

VAT rate out of range, or carrying more than two decimals

The rate is a percentage, not a fraction: fifteen per cent is written 15, never 0.15. The permitted windo...

BR-KSA-EN16931-01 Rejects the invoice

Business process (BT-23) is not reporting:1.0

One element at the head of every Saudi e-invoice carries the fixed text reporting:1.0. It is not a descri...

BR-KSA-EN16931-02 Rejects the invoice

Tax currency code (BT-6) is not SAR

The field whose presence BR-KSA-68 checks has its value checked here: three letters, SAR, and nothing els...

BR-KSA-EN16931-07 Rejects the invoice

Item net price not equal to gross price minus the price discount

When a line states a gross price, its net unit price must equal that gross price minus the price discount...

BR-KSA-EN16931-08 Warning

More than one tax total carrying the VAT breakdown

A document carries one tax total with the VAT breakdown inside it, and only one. A mixed basket split int...

BR-KSA-EN16931-09 Warning

Total VAT in SAR missing or duplicated

When the invoice declares the tax accounting currency, the schema wants exactly one tax total block with...

BR-KSA-EN16931-11 Warning

Line net amount not equal to quantity times unit price — the rounding trap

The invoice line net amount (BT-131) must equal the quantity times the item net price over the base quant...

BR-KSA-F-01 Warning

A date is not written YYYY-MM-DD

Every date on the invoice is written in the Gregorian calendar as YYYY-MM-DD: a four-digit year, a two-di...

BR-KSA-F-04 Rejects the invoice

Negative amount or quantity

Every amount and quantity in the document must be positive, except where the specification says otherwise...

BR-KSA-F-06-C19 Warning

Item name (BT-153) shorter than three characters, or longer than a thousand

The item name on an invoice line has two limits: a floor of three characters and a ceiling of a thousand....

BR-KSA-F-C-01 Warning

Item description unclear — Article 53 wants the invoice to say what was sold

A warning the live API returns when a line's description (BT-153) does not say what was sold: a serial nu...

How to read a rejection response from the Authority

The Authority does not send a text message. It sends a JSON object containing validationResults, which holds three lists. The code that stopped your invoice is in errorMessages — and whatever sits in warningMessages did not block acceptance.

A real response we logged

{
  "validationResults": {
    "infoMessages":    [{ "code": "XSD_ZATCA_VALID", "status": "PASS"  }],
    "warningMessages": [],
    "errorMessages":   [{ "code": "BR-CUSTOM-VALIDATION-01",
                          "category": "KSA",
                          "status": "ERROR" }],
    "status": "ERROR"
  },
  "reportingStatus": "NOT_REPORTED"
}

XSD_ZATCA_VALID with status PASS means the structure of the XML file is sound — the rejection came from a business rule, not from the file format.
status: ERROR at the result level means rejection. WARNING means acceptance with a warning.
reportingStatus: NOT_REPORTED means the invoice was not recorded, and the 24-hour deadline is still running.

Full reference

Every message text exactly as the Authority sends it in English, unedited.

138 codes

BR-CL-KSA-14 Rejects the invoice

Field character limit for QR Code field has been exceeded. The maximum character limit for this field is 1000 characters.

BR-CO-15 Rejects the invoice Read the guide →

Invoice total with VAT is not the total without VAT plus the VAT

Invoice total amount with VAT (BT-112)

BR-CUSTOM-VALIDATION-01 Rejects the invoice Read the guide →

Seller VAT number identical to the buyer VAT number

The Seller VAT registration number or seller group VAT registration number (BT-31) of The invoice must not match the buyer VAT registration number (BT-48) .

BR-KSA-03 Rejects the invoice Read the guide →

Invoice UUID missing or invalid

The invoice must contain a unique identifier ("UUID") (KSA-1) given by the unit that issued the document (unique message identifier for interchange process). This value must contain only letters, digits, and dashes.

BR-KSA-04 Rejects the invoice Read the guide →

Invoice date is in the future

The document issue date (BT-2) must be less or equal to the current date.

BR-KSA-05 Rejects the invoice Read the guide →

Invoice type (BT-3) holds a value that is not accepted

The invoice type code (BT-3) must be equal to one of value from the subset of UN/CEFACT code list 1001, D.16B agreed for KSA electronic invoices. Please refer paragraph 11.2.1 of XML implementation Standards.

BR-KSA-06 Rejects the invoice Read the guide →

Transaction type code (KSA-2) invalid — the NNPNESB structure

The invoice transaction code (KSA-2) must exist and respect the following structure: NNPNESB where NN (positions 1 and 2) = invoice subtype: - 01 for tax invoice - 02 for simplified tax invoice P (position 3) = 3rd Party invoice transaction, 0 for false, 1 for...

BR-KSA-07 Rejects the invoice

Self billing is not allowed (KSA-2, position 7 cannot be "1") for export invoices (KSA-2, position 5 = 1).

BR-KSA-08 Warning Read the guide →

Seller identification (BT-29) missing, repeated or not alphanumeric

The seller identification (BT-29) must exist only once with one of the scheme ID (BT-29-1) (CRN, MOM, MLS, SAG, OTH, 700) and must contain only alphanumeric characters. Commercial Registration number with "CRN" as schemeID. MOMRAH license with "MOM" as schemeI...

BR-KSA-09 Warning Read the guide →

Seller address incomplete on the invoice

Seller address must contain street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), district (KSA-3), country code (BT-40). For more information please access this link: https://splonline.com.sa/en/national-address-1/

BR-KSA-10 Warning Read the guide →

Buyer address incomplete — and the live message narrows it to a non-Saudi buyer

Buyer address must contain a street (BT-50), city (BT-52), country code (BT-55). This rule does not apply on the simplified tax invoices and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02).

BR-KSA-11 Rejects the invoice Read the guide →

Out-of-scope line carrying a non-zero rate

An Invoice line (BG-25) where the VAT category code (BT-151) is "Not subject to VAT", an invoiced item VAT rate (BT-152) shall be 0 (zero), if exist.

BR-KSA-12 Warning

A Document level allowance (BG-20) where VAT category code (BT-95) is "Not subject to VAT", a Document level allowance VAT rate (BT-96) shall be 0 (Zero), if exist.

BR-KSA-13 Warning

A Document level charge (BG-21) where the VAT category code (BT-102) is "Not subject to VAT", a Document level charge VAT rate (BT-103) shall be 0 (zero), if exist.

BR-KSA-14 Rejects the invoice Read the guide →

Buyer identification (BT-46) missing or without its scheme

The buyer identification (BT-46), required only if buyer is not VAT registered, then the buyer identification (BT-46) must be provided with one of the scheme IDs (BT-46-1) (TIN, CRN, MOM, MLS, 700, SAG, NAT, GCC, IQA, OTH) and must contain only alphanumeric ch...

BR-KSA-15 Warning Read the guide →

Tax invoice without a supply date (KSA-5)

The tax invoice ((invoice type code (BT-30) = 388) and (invoice transaction code (KSA-2) has "01" as first 2 digits)) must contain the supply date (KSA-5).

BR-KSA-16 Warning Read the guide →

Payment means code (BT-81) not in ZATCA's subset of UNTDID 4461

Payment means code (BT-81) in an invoice exist, then it must contain one of the values from subset of UNTDID 4461 code list

BR-KSA-17 Rejects the invoice Read the guide →

Note issued with no reason

Debit and credit note (invoice type code (BT-3) is equal to 383 or 381) must contain the reason (KSA-10) for this invoice type issuing.

BR-KSA-18 Rejects the invoice Read the guide →

Tax category code not accepted

VAT category code must contain one of the values (S, Z, E, O).

BR-KSA-19 Warning

Each Document level charge (BG-21) shall have a code for the reason for document level charge (BT-105).

BR-KSA-20 Warning

Each Invoice line charge (BG-28) shall have a code for the reason for invoice line charge (BT-145).

BR-KSA-21 Warning

Each Document level charge (BG-21) shall have a Reason for document level charge (BT-104).

BR-KSA-22 Warning

Each Invoice line charge (BG-28) shall have a Reason for invoice line charge (BT-144).

BR-KSA-23 Warning Read the guide →

Exempt category without an exemption reason code

A VAT breakdown (BG-23) with VAT Category code (BT-118) 'Exempt from VAT' shall have a VAT exemption reason code (BT-121).

BR-KSA-24 Warning Read the guide →

Out-of-scope category without a reason code

A VAT breakdown (BG-23) with VAT Category code (BT-118) 'Not subject to VAT' shall have a VAT exception reason code (BT-121)

BR-KSA-25 Warning

If it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) and the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA, then buyer name (BT-44) is mandatory.

BR-KSA-26 Warning Read the guide →

Previous invoice hash (PIH) in the wrong format

If the invoice contains the previous invoice hash (KSA-13), this hash must be base64 encoded SHA256. The hash shall be computed using the following method as described in the ds:transforms block in the XML Invoice Specifications: 1. Remove the <Invoice><ext:UB...

BR-KSA-27 Warning Read the guide →

QR code (KSA-14) missing from a simplified document, or not in the expected form

The document must contain a QR code (KSA-14), and this code must be base64Binary.

BR-KSA-28 Rejects the invoice

If the cryptographic stamp (KSA-15) exists in the invoice, this cryptographic stamp (KSA-15) must contain the exact "urn:oasis:names:specification:ubl:signature:1" value for signature information ID.

BR-KSA-29 Warning

If the cryptographic stamp (KSA-15) exists in the invoice, this cryptographic stamp (KSA-15) must contain the exact "urn:oasis:names:specification:ubl:signature:Invoice" value for referenced signature ID and signature ID.

BR-KSA-30 Rejects the invoice

The document cryptographic stamp (KSA-15) must contain the exact "urn:oasis:names:specification:ubl:dsig:enveloped:xades" value for signature method.

BR-KSA-31 Rejects the invoice Read the guide →

Transaction type not allowed on a simplified invoice — export and self-billing

For simplified tax invoices and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02),only the following transaction types can be "true": - third party (KSA-2, position 3 = 1), - nominal supply (KSA-2, position 4 = 1) and - summary transaction...

BR-KSA-33 Rejects the invoice Read the guide →

Invoice counter (ICV) missing or invalid

Each invoice must have an invoice counter value (KSA-16).

BR-KSA-34 Rejects the invoice Read the guide →

Invoice counter (ICV) holds something other than digits

The invoice counter value (KSA-16) contains only digits.

BR-KSA-35 Warning

If the invoice contains a supply end date (KSA-24), then the invoice must contain a supply date (KSA-5).

BR-KSA-36 Warning

If the invoice contains a supply end date (KSA-24), then this date must be greater than or equal to the supply date (KSA-5).

BR-KSA-37 Warning Read the guide →

Seller building number (KSA-17) is not 4 digits

The seller address building number must contain 4 digits.

BR-KSA-39 Rejects the invoice Read the guide →

Seller VAT number missing

The invoice must contain the seller VAT registration number or seller group VAT registration number (BT-31).

BR-KSA-40 Rejects the invoice Read the guide →

Seller VAT number invalid — 15 digits starting and ending with 3

If it exists in the invoice, the seller VAT registration number (BT-31) must contain 15 digits. The first and the last digits are "3"..

BR-KSA-42 Warning Read the guide →

Tax invoice without a buyer name (BT-44)

The buyer name (BT-44) must be present in the tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 01).

BR-KSA-44 Rejects the invoice Read the guide →

Buyer VAT number invalid on the invoice

If it exists in the invoice,the buyer VAT registration number or buyer group VAT registration number (BT-48) must contain 15 digits. The first digit and the last digit is "3".

BR-KSA-49 Rejects the invoice Read the guide →

Education or healthcare exemption with no buyer national ID

If the tax exemption reason code (BT-121) is equal to VATEX-SA-EDU or VATEX-SA-HEA, then the other buyer ID (BT-46) is mandatory and must be national ID (BT-46-1 = NAT).

BR-KSA-51 Warning Read the guide →

Line amount with VAT (KSA-12) not equal to line net plus line VAT

The line amount with VAT (KSA-12) must be Invoice line net amount (BT-131) + Line VAT amount (KSA-11).

BR-KSA-52 Rejects the invoice Read the guide →

Line VAT amount (KSA-11) missing

The line VAT amount (KSA-11) is mandatory for tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 01).

BR-KSA-53 Rejects the invoice Read the guide →

Line amount with VAT (KSA-12) missing

The line amount with VAT (KSA-12) is mandatory for tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 01).

BR-KSA-56 Warning Read the guide →

Credit or debit note with no reference to the original invoice

For credit notes ((BT-3) has the value of 381) and debit notes ((BT-3) has the value of 383), the billing reference ID (BT-25) is mandatory.

BR-KSA-60 Warning Read the guide →

Cryptographic stamp (KSA-15) missing from a simplified document

Cryptographic stamp (KSA-15) must exist in simplified tax invoices and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02).

BR-KSA-61 Warning Read the guide →

Previous invoice hash (PIH) missing from the invoice

Previous invoice hash (KSA-13) must exist in an invoice.

BR-KSA-63 Warning Read the guide →

Saudi buyer address incomplete on the invoice

If the buyer country code (BT-55) is "SA", then these fields are mandatory:street name (BT-50), building number (KSA-18), postal code (BT-53), city (BT-52), District (KSA-4), country code (BT-55).For more information please access this link:https://splonline.c...

BR-KSA-66 Warning Read the guide →

Seller postal code is not 5 digits

Seller postal code (BT-38) must be 5 digits.

BR-KSA-67 Warning Read the guide →

Buyer postal code is not 5 digits

If the buyer country code (BT-55) is "SA", then the Buyer postal code(BT-53) must be 5 digits.

BR-KSA-68 Rejects the invoice Read the guide →

Tax currency code (BT-6) missing

Tax currency code (BT-6) must exist in an invoice.

BR-KSA-69 Warning Read the guide →

Zero-rated category without an exemption reason code

A VAT breakdown (BG-23) with VAT Category code (BT-118) 'Zero rated' shall have a VAT exception reason code (BT-121).

BR-KSA-70 Rejects the invoice Read the guide →

Invoice issue time (KSA-25) missing or in the wrong format

The invoice must contain Invoice Issue Time (KSA-25). This value should be in the format: hh:mm:ss for time expressed in local time (eg 19:20:30) or hh:mm:ssZ for time expressed in UTC (eg 19:20:30Z).

BR-KSA-71 Warning

If the Invoice is a simplified invoice type and is a summary invoice (KSA-2, position 1 and 2 = 02, position 6 = 1),then the buyer name must be present.

BR-KSA-72 Rejects the invoice

If the Invoice is a simplified invoice type and is a summary invoice (KSA-2, position 1 and 2 = 02, position 6 = 1), then a supply date (KSA-5) and supply end date (KSA-24) must be present

BR-KSA-73 Warning

If Pre-Paid amount (BT-113) is provided, then the following data is mandatory to provide as additional invoice line(s) -Prepayment ID (KSA-26) -Sequential invoice number (BT-1) of the prepayment invoice(s)-Prepayment Issue Date (KSA-28) -Issue date (BT-2) of t...

BR-KSA-74 Rejects the invoice

Prepayment Document Type Code (KSA-30) for the Invoice line document reference must be '386'.

BR-KSA-75 Warning

If Prepayment Document Type code (KSA-30) is provided in an Invoice Line, then the following data is mandatory to provide in that invoice line - Prepayment VAT category Taxable Amount (KSA-31) - Sum total of taxable amounts subject to specific VAT Category cod...

BR-KSA-76 Warning

An Invoice line (BG-25) where the Prepayment VAT category code (KSA-33) is "Zero rated" the Prepayment VAT rate (KSA-34) shall be 0 (zero).

BR-KSA-77 Warning

An Invoice line (BG-25) where the Prepayment VAT category code (KSA-33) is "Exempt from VAT" the Prepayment VAT rate (KSA-34) shall be 0 (zero).

BR-KSA-78 Warning

An Invoice line (BG-25) where the Prepayment VAT category code (KSA-33) is "Not subject to VAT" the Prepayment VAT rate (KSA-34) shall be 0 (zero).

BR-KSA-79 Warning

The Prepayment VAT Category Tax Amount (KSA-32) must be Prepayment VAT category Taxable Amount( (KSA-31) x Prepayment VAT rate (KSA-34) /100).

BR-KSA-80 Warning

The Pre-Paid amount (BT-113) must be equal to the sum total of the Prepayment VAT category Taxable Amount (KSA-31) and the Prepayment VAT Category Tax Amount (KSA-32).

BR-KSA-81 Warning Read the guide →

Tax invoice to a buyer with neither a VAT number nor another ID (BT-46)

The other Buyer ID (BT-46) must present in the tax invoice and associated debit notes and credit notes (KSA-2, position 1 and 2 = 01), where the buyer VAT registration number or buyer group VAT registration number (BT-48) is not provided.

BR-KSA-82 Rejects the invoice

An Invoice line (BG-25) where Prepayment Document Type Code (KSA-30) is provided, then Item net price (BT-146); Invoice line allowance amount (BT-136); Invoice line charge amount (BT-141); Item line net amount (BT-131); line VAT amount (KSA-11); and line amoun...

BR-KSA-83 Warning Read the guide →

Exemption reason code without its reason text (BT-120)

A VAT breakdown (BG-23) with VAT Category code (BT-118) 'Exempt from VAT' or 'Zero rated' or 'Not subject to VAT' shall have a VAT exemption (or exception) reason text (BT-120) with one of the values from paragraph 11.2.4 of XML implementation standards on Tax...

BR-KSA-84 Rejects the invoice Read the guide →

VAT rate on a standard-rated item is neither 15 nor 5

The Document level allowance VAT rate (BT-96), Document level Charge VAT rate (BT-103), VAT category rate(BT-119), Invoiced item VAT rate (BT-152), Prepayment VAT rate(KSA-34) must be limited to one of the following values (5 or 15) when the relevant Document...

BR-KSA-85 Warning Read the guide →

Buyer phone number (BT-57) in an unaccepted format

The Buyer's contact phone number (BT-57) shall start with "0" or "+", followed by a maximum of 15 number and minimum 4 character after the "+" or "0" , if exist.

BR-KSA-86 Warning Read the guide →

Buyer email address (BT-58) in an unaccepted format

Buyer's Contact Email Address (BT-58) shall follow the following format ** [email protected] where: The [XXX] should consist of alphanumeric characters (a-z, A-Z, 0-9), dots ('.'), underscores ('_'), or hyphens ('-'). It must start and end with an alphanumeric charac...

BR-KSA-87 Warning

If the tax exchange rate (KSA-36) exists, then Source Currency Code (KSA-37), Target Currency Code (KSA-38) and Calculation Rate (KSA-39) shall be provided

BR-KSA-88 Rejects the invoice

If exist, Source Currency Code (KSA-37) must be the same as Invoice currency code (BT-5)

BR-KSA-89 Rejects the invoice

If exists, Target Currency Code (KSA-38) must be the same as the Tax currency code (BT-6)

BR-KSA-90 Rejects the invoice

If exists, the allowed maximum number of digits for the Tax Exchange Rate (KSA-39) is 14.

BR-KSA-91 Warning

For B2G supplies attracting provisions of Article 20(5) of VAT Regulations, Company Legal Form (KSA-40) should be provided with a static value "GOV" in case of a tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 01).

BR-KSA-92 Warning

If the Company Legal Form (KSA-40) is provided as 'GOV', then the Tax Point Date (BT-7) must present in a tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 01) and it must refer to the Payment Order Date.

BR-KSA-93 Warning

An Invoice line (BG-25) where the Prepayment VAT category code (KSA-33) is "Zero-rated" the Prepayment VAT exception reason code (KSA-41) should be provided.

BR-KSA-94 Warning

An Invoice line (BG-25) where the Prepayment VAT category code (KSA-33) is " Exempt from VAT " the Prepayment VAT exemption reason code (KSA-41) should be provided.

BR-KSA-95 Warning

An Invoice line (BG-25) where the Prepayment VAT category code (KSA-33) is " Not subject to VAT " the Prepayment VAT exception reason code (KSA-41) should be provided.

BR-KSA-96 Warning

An Invoice line (BG-25) with the Prepayment VAT category code (KSA-33) 'Exempt from VAT' or 'Zero rated' or 'Not subject to VAT' shall have a Prepayment VAT exemption(or exception) reason text (KSA-42) with one of the values from paragraph 11.2.4 of XML implem...

BR-KSA-97 Warning

If the Document Currency Code (BT-5) is different from "SAR", then the value in "Invoice total VAT amount (BT-110)" cannot be the same as the value in "Invoice total VAT amount in accounting currency (BT-111)".

BR-KSA-CL-01 Rejects the invoice Read the guide →

Invoice currency code (BT-5) is not an ISO 4217 code

Currency code (BT-5) must be according to ISO 4217:2005

BR-KSA-CL-02 Rejects the invoice Read the guide →

Mixed currency in the document — a currencyID attribute does not match the invoice currency

All currencyID attributes (BT-5) must have the same value as the invoice currency code (BT-5), except for the invoice total VAT amount in accounting currency (BT-111).

BR-KSA-CL-03 Rejects the invoice

Mime code must be according to subset of IANA code list.

BR-KSA-CL-04 Warning Read the guide →

Exemption reason code (BT-121) not on the list for its category

If VAT category Code (BT-118) is 'Z', or 'E', VAT exemption (or exception) reason code (BT-121) must exist with one of the values from paragraph 11.2.4 of XML implementation standards on Tax exemption (or exception) reason code - specific to Saudi Arabia.

BR-KSA-CL-06 Warning

Code for the reason for document level charge (BT-105) and the code for the reason for invoice line charge (BT-145) MUST be coded using UNTDID 7161 code list. https://unece.org/fileadmin/DAM/trade/untdid/d16b/tred/tred7161.htm

BR-KSA-CL-07 Warning

If the Prepayment VAT Category Code(KSA-33) is 'Z', or 'E' or 'O', the Prepayment VAT exemption (or exception) reason code(KSA-41) must exist with one of the values from paragraph 11.2.4 of XML implementation standards on Tax exemption (or exception) reason co...

BR-KSA-DEC-01 Rejects the invoice

The allowance percentage values (BT-94, BT-138) must be from 0.00 to 100.00, with maximum two decimal places. Only numerals are accepted, the percentage symbol (%) is not allowed.

BR-KSA-DEC-02 Rejects the invoice Read the guide →

VAT rate out of range, or carrying more than two decimals

The VAT rates (BT-96, BT-103, BT-119, BT-152, KSA-34) must be from 0.00 to 100.00, with maximum two decimals.Only numerals are accepted, the percentage symbol (%) is not allowed.

BR-KSA-DEC-03 Warning

VAT amount at line level (KSA-11) must have a maximum two decimals.

BR-KSA-DEC-04 Warning

Amount with VAT at line level (KSA-12) must have a maximum two decimals.

BR-KSA-DEC-06 Warning

Prepayment VAT category Taxable Amount (KSA-31) and Prepayment VAT Category Tax Amount (KSA-32) must have a maximum two decimals.

BR-KSA-EN16931-01 Rejects the invoice Read the guide →

Business process (BT-23) is not reporting:1.0

Business process (BT-23) must be "reporting:1.0".

BR-KSA-EN16931-02 Rejects the invoice Read the guide →

Tax currency code (BT-6) is not SAR

VAT accounting currency code (BT-6) must be "SAR".

BR-KSA-EN16931-03 Warning

Allowance/Charge amount (BT-92, BT-99, BT-136, BT-141) must equal base amount (BT-93, BT-100, BT-137, BT-142) * percentage (BT-94, BT-101, BT-138, BT-143) / 100 if base amount and percentage exists.

BR-KSA-EN16931-04 Warning

Allowance/Charge base amount (BT-93, BT-100, BT-137, BT-142) must be provided when allowance/Charge percentage (BT-94, BT-101,BT-138, BT-143) is provided.

BR-KSA-EN16931-05 Warning

Allowance/Charge percentage (BT-94, BT-101, BT-138, BT-143) must be provided when the allowance/Charge base amount (BT-93, BT-100, BT-137, BT-142) is provided.

BR-KSA-EN16931-06 Rejects the invoice

Charge on price level (BG-29) is allowed. The value of Indicator should be ' True'.

BR-KSA-EN16931-07 Rejects the invoice Read the guide →

Item net price not equal to gross price minus the price discount

Item net price (BT-146) must equal (Item Gross price (BT-148) - Allowance amount (BT-147)) when gross price is provided.

BR-KSA-EN16931-08 Warning Read the guide →

More than one tax total carrying the VAT breakdown

Only one tax total (BG-22) with tax subtotals must be provided.Refer to Calculation of VAT.

BR-KSA-EN16931-09 Warning Read the guide →

Total VAT in SAR missing or duplicated

Only one tax total (BG-22) without tax subtotals (BG-23) must be provided when tax currency code is provided .

BR-KSA-EN16931-11 Warning Read the guide →

Line net amount not equal to quantity times unit price — the rounding trap

Invoice line net amount (BT-131) must equal (Invoiced quantity (BT-129) * (Item net price (BT-146) / item price base quantity (BT-149))-) + Sum of invoice line charge amount (BT-141) - Sum of invoice line allowance amount (BT-136).

BR-KSA-EN16931-12 Rejects the invoice

Base quantity (BT-149) must be a positive number above zero.

BR-KSA-F-01 Warning Read the guide →

A date is not written YYYY-MM-DD

A date MUST be formatted YYYY-MM-DD, in accordance to the "Calendar date complete representation" as specified by ISO 8601:2004, format YYYY-MM-DD.

BR-KSA-F-02 Rejects the invoice

Allowance/Charge Indicator value MUST equal to 'false'/’True’ respectively.

BR-KSA-F-04 Rejects the invoice Read the guide →

Negative amount or quantity

All the document amounts and quantities must be positive, unless specified otherwise.

BR-KSA-F-05 Warning

Prepayment Issue Time (KSA-29) must be in the format: hh:mm:ss for time expressed in local time or hh:mm:ssZ for time expressed in UTC.(eg 19:20:30)

BR-KSA-F-06-C3 Warning

Field character limits for Purchase order ID field (BT-13) have not been met. The maximum limit is 127 characters.

BR-KSA-F-06-C4 Warning

Field character limits for the Seller Address - Street field (BT-35) have not been met. The minimum limit is 1 character and the maximum limit is 1000 characters.

BR-KSA-F-06-C5 Warning

Field character limits for Contract ID field (BT-12) have not been met. The maximum limit is 127 characters .

BR-KSA-F-06-C6 Warning

Field character limits for the Seller Address - Additional street field (BT-36) have not been met. The maximum limit is 127 characters.

BR-KSA-F-06-C7 Warning

Field character limits for the Seller Address - City field (BT-37) have not been met. The minimum limit is 1 character and the maximum limit is 127 characters.

BR-KSA-F-06-C9 Warning

Field character limits for the Seller Address - District field (KSA-3) have not been met. The minimum limit is 1 character and the maximum limit is 127 characters.

BR-KSA-F-06-C11 Warning

Field character limits for the Buyer Address - Additional street field (BT-51) have not been met. The maximum limit is 127 characters.

BR-KSA-F-06-C12 Warning

Field character limits for Buyer name field (BT-44) have not been met. The minimum limit is 1 character and the maximum limit is 1000 characters.

BR-KSA-F-06-C13 Warning

Field character limits for Reasons for issuance of credit / debit note field (KSA-10) have not been met. The minimum limit is 1 character and the maximum limit is 1000 characters .

BR-KSA-F-06-C14 Warning

Field character limits for Payment terms field (KSA-22) have not been met. The maximum limit is 1000 characters.

BR-KSA-F-06-C15 Warning

Field character limits for Payment account identifier field (BT-84) have not been met. The maximum limit is 127 characters.

BR-KSA-F-06-C16 Warning

Field character limits for VAT exemption reason text field (BT-120) have not been met. The minimum limit is 1 character and the maximum limit is 1000 characters.

BR-KSA-F-06-C19 Warning Read the guide →

Item name (BT-153) shorter than three characters, or longer than a thousand

Field character limits for Item name field (BT-153) have not been met. The minimum limit is 3 character and the maximum limit is 1000 characters.

BR-KSA-F-06-C21 Warning

Field character limits for Item price base quantity unit code field (BT-150) have not been met. The maximum limit is 127 characters.

BR-KSA-F-06-C22 Rejects the invoice

Field character limits for Billing reference ID field (BT-25) have not been met. The minimum limit is 1 character and the maximum limit is 5000 characters.

BR-KSA-F-06-C23 Warning Read the guide →

Buyer street (BT-50) empty, or longer than the limit

Field character limits for the Buyer Address - Street field (BT-50) have not been met. The minimum limit is 1 character and the maximum limit is 1000 characters.

BR-KSA-F-06-C24 Warning

Field character limits for the Buyer Address - Street field (BT-50) have not been met. The maximum limit is 1000 characters.

BR-KSA-F-06-C25 Warning Read the guide →

Buyer city (BT-52) empty, or longer than the limit

Field character limits for the Buyer Address - City field (BT-52) have not been met. The minimum limit is 1 character and the maximum limit is 127 characters.

BR-KSA-F-06-C26 Warning

Field character limits for the Buyer Address - City field (BT-52) have not been met. The maximum limit is 127 characters.

BR-KSA-F-06-C28 Warning Read the guide →

Buyer district (KSA-4) empty, or longer than the limit

Field character limits for the Buyer Address - District field (KSA-4) have not been met. The minimum limit is 1 character and the maximum limit is 127 characters.

BR-KSA-F-06-C29 Warning

Field character limits for the Buyer Address - District field (KSA-4) have not been met. The maximum limit is 127 characters.

BR-KSA-F-06-C32 Warning

Field character limits for Buyer name field (BT-44) have not been met. The maximum limit is 1000 characters.

BR-KSA-F-06-C33 Warning

Field character limits for Reason for the document level charge (BT-104) have not been met. The maximum limit is 1,000 characters.

BR-KSA-F-06-C34 Warning

Field character limits for Reason for invoice line charge (BT-144) have not been met. The maximum limit is 1,000 characters.

BR-KSA-F-06-C35 Warning

Field character limits for Reason for the document level allowance (BT-97) have not been met. The maximum limit is 1,000 characters.

BR-KSA-F-06-C36 Warning

Field character limits for Reason for the invoice line allowance (BT-139) have not been met. The maximum limit is 1,000 characters.

BR-KSA-F-06-C37 Warning

Field character limits for the contact name - Buyer's contact point field (BT-56) have not been met. The maximum limit is 1000 characters.

BR-KSA-F-06-C38 Warning

Field character limits for the contact note - Buyer's Contact Note field (KSA-35) have not been met. The maximum limit is 1000 characters.

BR-KSA-F-06-C39 Warning

Field character limits for the Prepayment VAT exemption reason text (KSA-42) have not been met. The maximum limit is 1000 characters.

BR-KSA-F-13 Warning Read the guide →

Additional seller or buyer identifier holds an invalid value

Please recheck Other Seller/Buyer ID (BT-29 or BT-46) as it contains an invalid value.

BR-KSA-F-C-01 Warning Read the guide →

Item description unclear — Article 53 wants the invoice to say what was sold

Please recheck Item Description (BT-153) providing unclear description violates the requirements specified in Article 53 of VAT Regulations.

Source: ZATCA e-Invoicing SDK — compiled validation schematron (20210819_ZATCA_E-invoice_Validation_Rules.xsl, SDK version Java 238 R3.3.9), extracted on 2026-07-30. The message texts belong to the Authority and are shown as they are; the explanations are by ZATCA Tools.

Frequently asked questions

What is the difference between an error and a warning in the Authority's response? +

An ERROR rejects the invoice, so it is never registered with the Authority and must be corrected and resubmitted. A WARNING does not block acceptance: the invoice is accepted as "accepted with warnings" and is legally valid, but it carries details worth fixing. Of 138 codes, 45 reject the invoice and 93 are warnings.

Where do I find the error code in the Authority's response? +

The Authority's response is a JSON object containing validationResults, which holds three lists: infoMessages, warningMessages and errorMessages. Each entry carries code, category and message. The code that rejects your invoice is the one inside errorMessages.

My invoice was rejected — do I owe a fine? +

A rejection is not itself a fine. But a simplified tax invoice must be reported within 24 hours of being issued, and a tax invoice needs clearance before you send it to the customer. If the deadline passes while the invoice is still rejected, you are in breach. Correct it and send it again the same day.

Where did this list come from? +

From the schematron validation rules published inside the Zakat, Tax and Customs Authority's e-invoicing SDK, version Java 238 R3.3.9. The message texts are reproduced verbatim as the Authority sends them in English; the explanations are ours.

Is the list complete? +

It covers everything the published validation rules state. We have also seen the live API return codes that are not in that release — we added those from real rejection responses we logged. If you receive a code that is not here, tell us and we will add it.

Most of these codes never reach you at all

The PIH, the counter, the encoding and the signature are all built for you in ZATCA Tools — no fields to fill in, no rules to memorise. Start free, with no credit card.

Start for free