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 135 codes, 44 reject the invoice and 91 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-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-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-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-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-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-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-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....

Invoice type and transaction coding

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

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

Only three values are accepted: 388 invoice, 381 credit note, 383 debit note. And why Phase 2 has no canc...

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-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-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-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-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...

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.

135 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-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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

BR-KSA-69 Warning

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

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)."The invoice must contain Invoice Issue Time (KSA-25). This...

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

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

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

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

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

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

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

BR-KSA-CL-02 Rejects the invoice

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

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

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

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

BR-KSA-EN16931-02 Rejects the invoice

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

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

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

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

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-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

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

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

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.

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 135 codes, 44 reject the invoice and 91 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. Completely free for now, and no credit card.

Start for free