# Fix ZATCA validation errors

Find the ZATCA rule behind a rejected Saudi invoice and correct it. Start with the document type you sent and the errors returned by Unify or ZATCA.

A Saudi invoice is checked three times: Unify checks the GETS request, then the e-invoice built from it, then ZATCA checks the e-invoice when it clears or receives the report. The rule IDs come from ZATCA’s [XML Implementation Standard](https://zatca.gov.sa/en/E-Invoicing/SystemsDevelopers/Pages/E-Invoice-specifications.aspx): `BR-KSA-*` rules are ZATCA’s own, and `BR-*` rules come from EN 16931, the European invoice standard ZATCA builds on.

## Check the GETS request

Select **Saudi Arabia** and the document type in the [field reference](https://docs.complyance.io/countries/sa/fields/). The **Requirement** column shows which GETS fields are mandatory, optional or conditional. In **List with sample request**, choose the document type and inspect the fields for that selection. Use values from the invoice and the company’s registration records.

## Read a `422` response

A `422` response from Unify lists each failed rule in `errors`. `code` is the rule ID, `getsPath` names the GETS field to correct and `message` describes the rule. Correct the source data, then send the document again. See [Unify errors](https://docs.complyance.io/api-reference/unify/errors/) for the response format.

If the e-invoice built from your request fails a ZATCA rule, the `422` has `validationStage` set to `xml` and an empty `errors` list. [Get the document](https://docs.complyance.io/api-reference/unify/submit-and-retrieve/#follow-the-document) by its `documentId` to see the rule IDs in its `errors`.

## Read ZATCA’s result

After the `200`, [follow the document](https://docs.complyance.io/api-reference/unify/submit-and-retrieve/#follow-the-document) until `isTerminal` is `true`. `final_valid` means ZATCA cleared the standard invoice or accepted the report of a simplified invoice. `final_invalid` means ZATCA rejected it: `government.status` is `REJECTED`, and `government` also holds ZATCA’s validation messages with their rule IDs. Correct the invoice and send it as a new document.

Keep the original tax and amount values supplied by the issuer. Do not replace missing values with guessed ones.

## Every rule Unify checks

These are the 87 rules Unify applies to a Saudi GETS request, with the message you get back and the field it points at. **Applies to** shows the document types, modifiers or variant each rule belongs to. Search by the `code` from a `422` response or by a word from the message. ZATCA’s own checks after submission follow the same `BR-KSA-*` rules.

| Rule | What it checks | Field | Applies to |
| - | - | - | - |
| `BR-CL-KSA-14` | QR code field length must be between 1 and 1000 characters. | `extensions.sa_qrCode` | Every document type |
| `BR-KSA-03` | Invoice must contain a UUID (KSA-1) using letters, digits, and dashes. | `header.uuid` | Every document type |
| `BR-KSA-04` | Document issue date (BT-2) must be less than or equal to current date. | `header.issueDate` | Every document type |
| `BR-KSA-07` | Self-billing is not allowed for export invoices. | `header.documentType` | Modifier `self_billed` |
| `BR-KSA-08` | Seller identification (BT-29) must exist once, use one of CRN, MOM, MLS, SAG, OTH, 700, and be alphanumeric. | `parties.seller.registrationNumbers` | Every document type |
| `BR-KSA-09` | Seller address must contain street, building number, postal code, city, district, and country code. | `parties.seller.address` | Every document type |
| `BR-KSA-10` | If buyer country is not SA, buyer address must contain street, city, and country code; does not apply to simplified documents. | `parties.buyer.address` | Every document type |
| `BR-KSA-11` | If line VAT category is O, line VAT rate must be 0 if present. | `lineItems` | Every document type |
| `BR-KSA-12` | If document allowance VAT category is O, allowance VAT rate must be 0 if present. | `allowancesAndCharges` | Every document type |
| `BR-KSA-13` | If document charge VAT category is O, charge VAT rate must be 0 if present. | `allowancesAndCharges` | Every document type |
| `BR-KSA-14` | If buyer is not VAT registered, buyer identification (BT-46) is required with an allowed scheme from TIN, CRN, MOM, MLS, 700, SAG, NAT, GCC, IQA, PAS, OTH. | `parties.buyer.registrationNumbers` | Every document type |
| `BR-KSA-16` | If payment means code (BT-81) exists, it must come from the allowed UNTDID 4461 subset. | `payment.paymentMeans` | Every document type |
| `BR-KSA-17` | Credit notes (381) and debit notes (383) must contain note issuance reason (KSA-10). | `header.noteIssuanceReason` | Credit note, debit note, simplified credit note, simplified debit note |
| `BR-KSA-18` | VAT category code must be one of S, Z, E, O. | `taxTotals` | Every document type |
| `BR-KSA-19` | Each document-level charge should have a charge reason code (BT-105). | `allowancesAndCharges` | Every document type |
| `BR-KSA-20` | Each line charge should have a charge reason code (BT-145). | `lineItems` | Every document type |
| `BR-KSA-21` | Each document-level charge should have a charge reason (BT-104). | `allowancesAndCharges` | Every document type |
| `BR-KSA-22` | Each line charge should have a charge reason (BT-144). | `lineItems` | Every document type |
| `BR-KSA-23` | Exempt from VAT VAT breakdowns should have VAT exemption reason code. | `taxTotals` | Every document type |
| `BR-KSA-24` | Not subject to VAT VAT breakdowns should have VAT exception reason code. | `taxTotals` | Every document type |
| `BR-KSA-27` | Simplified invoice documents must contain a QR code (KSA-14) encoded as base64 text. | `extensions.sa_qrCode` | Simplified invoice, simplified credit note, simplified debit note |
| `BR-KSA-31` | Self-billing is not allowed for simplified invoices and associated simplified notes. | `header.documentType` | Modifier `self_billed` |
| `BR-KSA-33` | Invoice must contain invoice counter value (KSA-16). | `extensions.sa_icv` | Every document type |
| `BR-KSA-34` | Invoice counter value (KSA-16) must contain digits only. | `extensions.sa_icv` | Every document type |
| `BR-KSA-35` | If supply end date (KSA-24) exists, supply date (KSA-5) must also exist. | `header.invoicePeriod` | Modifier `continuous_supply` |
| `BR-KSA-36` | If supply end date exists, it must be greater than or equal to supply date. | `header.invoicePeriod` | Modifier `continuous_supply` |
| `BR-KSA-37` | Seller building number must contain 4 digits. | `parties.seller.address.additionalAddressData.buildingNumber` | Every document type |
| `BR-KSA-39` | Invoice must contain seller VAT registration number or seller group VAT registration number (BT-31). | `parties.seller.taxIds` | Every document type |
| `BR-KSA-40` | If present, seller VAT registration number must contain 15 digits and start/end with 3. | `parties.seller.taxIds` | Every document type |
| `BR-KSA-42` | Buyer name must be present in tax invoices and associated notes. | `parties.buyer.name` | Every document type |
| `BR-KSA-44` | If present, buyer VAT number must contain 15 digits and start/end with 3. | `parties.buyer.taxIds` | Every document type |
| `BR-KSA-51` | Line amount with VAT (KSA-12) must equal line net amount plus line VAT amount. | `lineItems` | Every document type |
| `BR-KSA-52` | Line VAT amount (KSA-11) is mandatory for tax invoices and associated notes. | `lineItems` | Tax invoice |
| `BR-KSA-53` | Line amount with VAT (KSA-12) is mandatory for tax invoices and associated notes. | `lineItems` | Tax invoice |
| `BR-KSA-56` | Credit notes and debit notes must contain billing reference ID (BT-25). | `header.referenceId` | Credit note, debit note, simplified credit note, simplified debit note |
| `BR-KSA-60` | Simplified invoices and associated simplified notes must contain a cryptographic stamp (KSA-15). | `extensions.sa_digitalSignature` | Simplified invoice, simplified credit note, simplified debit note |
| `BR-KSA-63` | If buyer country code is SA, buyer address must contain street, building number, postal code, city, district, and country code. | `parties.buyer.address` | Every document type |
| `BR-KSA-66` | Seller postal code must be 5 digits. | `parties.seller.address.postalCode` | Every document type |
| `BR-KSA-67` | If buyer country code is SA, buyer postal code must be 5 digits. | `parties.buyer.address.postalCode` | Every document type |
| `BR-KSA-68` | Tax currency code (BT-6) must exist. | `header.taxCurrency` | Every document type |
| `BR-KSA-69` | Zero rated VAT breakdowns should have VAT exception reason code. | `taxTotals` | Every document type |
| `BR-KSA-71` | Simplified summary invoices must contain buyer name. | `parties.buyer.name` | Modifier `summary` |
| `BR-KSA-72` | Simplified summary invoices must contain supply date and supply end date. | `header.invoicePeriod` | Modifier `summary` |
| `BR-KSA-73` | If prepaid amount exists, invoice must provide prepayment line references including prepayment ID, issue date/time, and document type code 386. | `extensions` | Variant `prepayment` |
| `BR-KSA-74` | Prepayment document type code (KSA-30) on invoice-line document reference must be 386. | `extensions.sa_prepaymentTypeCode` | Variant `prepayment` |
| `BR-KSA-75` | If prepayment document type code exists, prepayment taxable amount, tax amount, tax category code, and tax rate are mandatory on that line. | `extensions` | Variant `prepayment` |
| `BR-KSA-76` | If prepayment VAT category is Zero rated, prepayment VAT rate must be 0. | `extensions.sa_prepaymentTaxRate` | Variant `prepayment` |
| `BR-KSA-77` | If prepayment VAT category is Exempt from VAT, prepayment VAT rate must be 0. | `extensions.sa_prepaymentTaxRate` | Variant `prepayment` |
| `BR-KSA-78` | If prepayment VAT category is Not subject to VAT, prepayment VAT rate must be 0. | `extensions.sa_prepaymentTaxRate` | Variant `prepayment` |
| `BR-KSA-79` | Prepayment VAT tax amount must equal taxable amount multiplied by prepayment VAT rate divided by 100. | `extensions` | Variant `prepayment` |
| `BR-KSA-80` | Prepaid amount must equal prepayment taxable amount plus prepayment tax amount. | `totals.prepaidAmount` | Variant `prepayment` |
| `BR-KSA-81` | For tax invoices and associated notes, if buyer VAT number is not provided, another buyer ID must be provided. | `parties.buyer` | Tax invoice |
| `BR-KSA-83` | Z, E, or O VAT breakdowns should have Saudi-specific VAT exemption/exception reason text. | `taxTotals` | Every document type |
| `BR-KSA-84` | Standard-rate VAT percentages may only be 5 or 15 across allowance, charge, subtotal, line, and prepayment contexts. | `taxTotals` | Every document type |
| `BR-KSA-87` | If tax exchange rate exists, source currency, target currency, and calculation rate must all be present. | `header.exchangeRate` | Every document type |
| `BR-KSA-88` | Source currency code (KSA-37) must match invoice currency code (BT-5). | `header.exchangeRate.sourceCurrency` | Every document type |
| `BR-KSA-89` | Target currency code (KSA-38) must match tax currency code (BT-6). | `header.exchangeRate.targetCurrency` | Every document type |
| `BR-KSA-90` | Tax exchange rate (KSA-39) may have at most 14 digits. | `header.exchangeRate.rate` | Every document type |
| `BR-KSA-92` | If transaction type is B2G, contract ID (BT-12) must be present in tax invoices and associated notes. | `extensions.sa_contractReference` | Modifier `b2g` |
| `BR-KSA-97` | If document currency is not SAR, total VAT amount and total VAT amount in accounting currency must not be equal. | `totals` | Every document type |
| `BR-KSA-98` | Simplified invoice should be submitted within 24 hours of issue date/time. | `header.issueDate` | Simplified invoice, simplified credit note, simplified debit note |
| `BR-KSA-99` | If buyer VAT number exists in tax invoices and associated notes, it should not be left empty. | `parties.buyer.taxIds` | Every document type |
| `BR-KSA-CL-03` | Mime code must be from the allowed IANA subset. | `supportingDocuments` | Every document type |
| `BR-KSA-CL-06` | Document-level and line-level charge reason codes must use UNTDID 7161. | `allowancesAndCharges` | Every document type |
| `BR-KSA-DEC-01` | Allowance percentages must be between 0.00 and 100.00 with at most two decimals. | `allowancesAndCharges` | Every document type |
| `BR-KSA-DEC-02` | VAT rates must be between 0.00 and 100.00 with at most two decimals. | `taxTotals` | Every document type |
| `BR-KSA-DEC-03` | Line VAT amount (KSA-11) must have at most two decimals. | `lineItems` | Every document type |
| `BR-KSA-DEC-04` | Line amount with VAT (KSA-12) must have at most two decimals. | `lineItems` | Every document type |
| `BR-KSA-EN16931-02` | VAT accounting currency code (BT-6) must be SAR. | `header.taxCurrency` | Every document type |
| `BR-KSA-EN16931-03` | Allowance/charge amount must equal base amount multiplied by percentage divided by 100 when both exist. | `allowancesAndCharges` | Every document type |
| `BR-KSA-EN16931-04` | Allowance/charge base amount must be present when percentage is present. | `allowancesAndCharges` | Every document type |
| `BR-KSA-EN16931-05` | Allowance/charge percentage must be present when base amount is present. | `allowancesAndCharges` | Every document type |
| `BR-KSA-EN16931-08` | Only one tax total with subtotals should be provided. | `taxTotals` | Every document type |
| `BR-KSA-EN16931-09` | Only one tax total without subtotals should be provided when tax currency exists. | `taxTotals` | Every document type |
| `BR-KSA-EN16931-11` | Invoice line net amount must reconcile from quantity, price, line charges, and line allowances. | `lineItems` | Every document type |
| `BR-KSA-EN16931-12` | Base quantity must be above zero. | `lineItems` | Every document type |
| `BR-KSA-F-01` | Dates must be formatted YYYY-MM-DD. | `header.issueDate` | Every document type |
| `BR-KSA-F-02` | Allowance/charge indicator must correctly use false or true. | `allowancesAndCharges` | Every document type |
| `BR-KSA-F-04` | Document amounts and quantities must be positive unless explicitly allowed otherwise. | `totals` | Every document type |
| `BR-KSA-F-06-C3` | Purchase order ID (BT-13) maximum length is 127. | `extensions.sa_purchaseOrderReference` | Every document type |
| `BR-KSA-F-06-C5` | Contract ID (BT-12) maximum length is 127. | `extensions.sa_contractReference` | Every document type |
| `BR-KSA-F-06-C14` | Payment terms (KSA-22) maximum length is 1000 characters. | `payment.paymentTerms` | Every document type |
| `BR-KSA-F-06-C15` | Payment account identifier (BT-84) maximum length is 127 characters. | `payment.paymentMeans` | Every document type |
| `BR-KSA-F-06-C33` | Document-level charge reason (BT-104) maximum length is 1000 characters. | `allowancesAndCharges` | Every document type |
| `BR-KSA-F-06-C34` | Line charge reason (BT-144) maximum length is 1000 characters. | `lineItems` | Every document type |
| `BR-KSA-F-06-C35` | Document-level allowance reason (BT-97) maximum length is 1000 characters. | `allowancesAndCharges` | Every document type |
| `BR-KSA-F-06-C36` | Line allowance reason (BT-139) maximum length is 1000 characters. | `lineItems` | Every document type |

Source: https://docs.complyance.io/countries/sa/validation-rules/