Skip to content

Saudi Arabia · E-invoicing

ZATCA E-Invoice Errors: BR-KSA Codes and How to Fix Them

7 min read Published:

In short

ZATCA rejects an e-invoice when it breaks even one validation rule (an error) and accepts it with warnings when the problem is minor. Most errors carry a BR-KSA code: a buyer VAT number that is not 15 digits starting and ending with 3 (BR-KSA-44), an incomplete Saudi address (BR-KSA-63), a wrong transaction code (BR-KSA-06) or totals that do not add up (BR-CO-15). Fix the source data and submit a new document.

Last verified: · Source: ZATCA E-Invoice XML Implementation Standard · How we verify

Download PDF

Errors and warnings: rejected or accepted

Every invoice, credit note and debit note you send to Fatoora comes back with one of three outcomes. ZATCA defines them plainly: an error is a validation failure on a rejected document, a warning is a validation failure on an accepted document, and a document with even one error is rejected entirely.

Warnings are not a free pass. ZATCA says warnings are temporarily accepted and might become rejections in the future, and that taxpayers who keep sending them may be investigated. Its own example of a minor mistake that is accepted with warnings is a missing building number in the address. Fix warnings on the next invoice; fix errors before anything else.

Fatoora responses and what to do
ResponseWhat it meansWhat to do
200 Accepted: cleared (standard) or reported (simplified) Nothing
202 Accepted with warnings Pass the warnings to whoever maintains your invoicing system and fix the data before the next invoice
400 Rejected: at least one error Read the error codes, correct the data and submit a new document
401 Unauthorized Check the authentication certificate (CSID) and secret, then resubmit
303 Clearance switched off Submit the standard invoice through the reporting API instead
429, 500, 503, 504 ZATCA did not receive the invoice Send the same invoice again

How to read a ZATCA error code

Fatoora checks each document in layers: the UBL 2.1 schema, then a subset of the European EN 16931 rules, then the KSA rules, and for simplified (B2C) documents the QR code and your cryptographic stamp. Where a KSA rule and an EN 16931 rule cover the same point, the KSA rule wins.

The code tells you which layer failed. BR- and BR-CO- codes are EN 16931 rules (BR-CO are the arithmetic checks). BR-KSA- codes are Saudi rules, with families for decimals (BR-KSA-DEC), code lists (BR-KSA-CL), formats (BR-KSA-F) and Saudi changes to EN 16931 (BR-KSA-EN16931). The message names the field by its term number, such as BT-48 for the buyer VAT number or KSA-2 for the transaction code.

Nearly every error traces back to master data: the customer record, your company profile or a tax rate. Fix it there once and every later invoice passes.

Buyer and seller data errors

Frequent BR-KSA errors in party data
RuleWhat it meansHow to fix
BR-KSA-44 Buyer VAT number is not 15 digits starting and ending with 3 Correct the VAT number on the customer record, digits only
BR-KSA-46 An export invoice carries a buyer VAT number Leave the VAT number off customers abroad; give another ID instead
BR-KSA-81 Standard invoice with no buyer VAT number and no other buyer ID Add another ID such as the CR number, national ID or Iqama number
BR-KSA-14 Other buyer ID has a wrong scheme or characters Use TIN, CRN, MOM, MLS, 700, SAG, NAT, GCC, IQA, PAS or OTH, with letters and digits only
BR-KSA-42 Buyer name missing on a standard invoice Fill in the customer legal name
BR-KSA-63 Saudi buyer address incomplete Fill street, building number, postal code, city and district from the national address
BR-KSA-67 Saudi buyer postal code is not 5 digits Correct the postal code on the customer record
BR-KSA-10 Buyer address incomplete on a standard invoice A non-Saudi buyer needs at least street, city and country
BR-KSA-09 Seller address incomplete Fill street, building number, postal code, city and district on your company profile
BR-KSA-37 / BR-KSA-66 Seller building number not 4 digits, or postal code not 5 digits Copy both exactly from your national address
BR-KSA-40 Seller VAT number is not 15 digits starting and ending with 3 Use the VAT number from your ZATCA registration certificate
BR-KSA-08 Seller ID missing, repeated or with a wrong scheme Give one ID: CRN, MOM, MLS, 700, SAG or OTH, in that order of priority

Invoice type code and transaction flags (BR-KSA-05, BR-KSA-06)

Two fields decide how ZATCA treats a document. The invoice type code (BR-KSA-05) must be 388 for a tax invoice, 381 for a credit note, 383 for a debit note or 386 for a prepayment invoice. The transaction code (KSA-2, checked by BR-KSA-06) is a seven-digit string of flags written into the same element.

  • BR-KSA-07: an export invoice (position 5 = 1) cannot also be self-billed (position 7 = 1)
  • BR-KSA-31: a simplified invoice may only set the third-party, nominal and summary flags
  • BR-KSA-17: a credit or debit note must give the reason it was issued (KSA-10)
  • BR-KSA-56: a credit or debit note must reference the original invoice number (BT-25)
  • BR-KSA-15: a standard tax invoice must carry the supply date (KSA-5)
  • BR-KSA-71 / BR-KSA-72: a simplified summary invoice needs the buyer name and both supply dates

Reading the transaction code (KSA-2)

  • Positions 1–2: 01 standard tax invoice (cleared) or 02 simplified tax invoice (reported)
  • Position 3: third-party invoice · position 4: nominal supply · position 5: export
  • Position 6: summary invoice · position 7: self-billed invoice (1 = yes, 0 = no)
  • Standard tax invoice, no flags: 0100000 with type code 388
  • Simplified tax invoice, no flags: 0200000 with type code 388

Hash chain, counter, QR and stamp errors

Every document carries the hash of the document before it (the previous invoice hash, PIH) and an invoice counter value (ICV). ZATCA requires one sequence per e-invoicing unit, shared by standard and simplified documents, and records the hash of rejected documents too. So the PIH must point to the last document your unit generated, not the last one ZATCA accepted. An invoice issued outside the integrated system breaks the chain.

  • BR-KSA-61: every document must carry the previous invoice hash
  • BR-KSA-26: the PIH must be a base64-encoded SHA-256 hash computed the way the standard describes; for the very first document it is the hash of the character 0
  • BR-KSA-33 / BR-KSA-34: every document needs an invoice counter value made of digits only; ZATCA adds that a counter value is never reused
  • BR-KSA-03: the UUID may contain only letters, digits and dashes
  • BR-KSA-27: the document must contain a QR code encoded in base64
  • BR-KSA-60: simplified documents must carry your cryptographic stamp, because ZATCA does not stamp them
  • BR-KSA-28, BR-KSA-29, BR-KSA-30: the signature block must use the exact identifiers and signature method the standard gives

Totals, rounding and decimals

The arithmetic rules reject an invoice whose numbers do not add up. Line net amounts must sum to the invoice line total (BR-CO-10); the total without VAT is that sum less document allowances plus charges (BR-CO-13); the VAT total must equal the sum of the VAT breakdown (BR-CO-14); and the total with VAT must equal the total without VAT plus VAT (BR-CO-15).

Most failures are rounding. Each VAT category amount must equal its taxable amount times the rate, rounded to two decimals (BR-CO-17, and BR-S-09 for standard-rated lines). Pick one rounding method and keep it on every line and every invoice.

  • BR-KSA-51: on each line, the amount with VAT must equal the line net amount plus the line VAT
  • BR-KSA-EN16931-11: the line net amount must equal quantity × net price, plus line charges, minus line allowances
  • BR-KSA-DEC-02: VAT rates are numbers from 0.00 to 100.00 with at most two decimals, without the % sign
  • BR-KSA-DEC-03 / BR-KSA-DEC-04: line VAT and line amount with VAT have at most two decimals
  • BR-KSA-F-04: amounts and quantities must be positive; a return is a credit note, not a negative line
  • BR-KSA-68 and BR-KSA-EN16931-02: the tax currency code must be present and must be SAR

Dates, times and VAT categories

  • BR-KSA-04: the issue date cannot be later than the current date; check the clock and time zone of the device that issues invoices
  • BR-KSA-70: the issue time is hh:mm:ss in Saudi time or hh:mm:ssZ in UTC; a UTC time without the Z is read as Saudi time
  • BR-KSA-F-01: dates are written YYYY-MM-DD
  • BR-KSA-36: a supply end date cannot be earlier than the supply date
  • BR-KSA-18: the VAT category is S, Z, E or O, nothing else
  • BR-KSA-69, BR-KSA-23, BR-KSA-24: zero-rated, exempt and out-of-scope amounts need an exemption reason code, taken from ZATCA's VATEX list (BR-KSA-CL-04) with its matching text (BR-KSA-83)
  • BR-KSA-F-03 and BR-KSA-F-06: no empty elements, and every field within the character limits in the data dictionary

Certificate (CSID) and onboarding errors

These problems are not BR rules, but they stop every invoice. ZATCA states that invoices signed with an invalid certificate are rejected; the API answers 401 when the authentication certificate or secret is wrong.

  • During onboarding, ZATCA lists the usual CSR errors: an OTP that is not six digits, an OTP generated for another VAT number, an expired OTP, an invalid VAT number and missing fields
  • If a compliance check fails, the unit starts again with a new OTP and a new CSR
  • The production CSID expires. Renew it before the expiry date; renewal revokes the old CSID and issues a new one
  • An invoice cleared in the sandbox or simulation environment is a test. It is not a valid invoice to give a buyer

Fixing a rejected invoice the right way

  • Standard invoice rejected: it is not a valid tax invoice and must not go to the buyer. Correct the data and submit it as a new document with its own UUID, counter value, hash and time stamp
  • Simplified invoice rejected after issue: the customer already has it. Fix the cause and submit a corrected document for reporting; ZATCA does not expect you to reissue it to the customer
  • Never edit a cleared invoice. Correct it with a credit or debit note that references it, which is itself cleared or reported
  • Keep the chain: the new document's PIH is the hash of the document generated just before it, even if that was the rejected one
  • Warnings: the document stands; fix the customer or company data so the next one is clean
  • VAT still applies: ZATCA notes that a technical rejection does not cancel the sale, so the VAT is still due in your return

How ERP HRM Solution handles ZATCA responses

ERP HRM Solution connects to Fatoora with your own onboarding: you generate the OTP in the Fatoora portal, the software creates the CSR, runs ZATCA's compliance checks for your unit and receives your production CSID under Settings → E-invoicing. It is not listed in ZATCA's directory of e-invoicing solution providers.

A standard invoice is cleared when you issue it. If ZATCA rejects it, it stays a draft with each error code and message shown, so you fix the record and issue again; an invoice accepted with warnings is marked ZATCA cleared (warnings) with the warnings listed. Simplified invoices are reported in the background with retries, and the company is alerted when one is still unreported 20 hours after it was created. The hash chain moves on after a rejection, as ZATCA requires, and the software warns 30 days before the CSID expires.

Frequently asked questions

An error rejects the document: a standard invoice is not cleared and is not a valid tax invoice. A warning is a validation failure on a document ZATCA still accepts. ZATCA says warnings might become rejections in the future, so fix the data behind them.

The buyer VAT number on a non-export invoice is not 15 digits with 3 as the first and last digit. Correct the VAT number on the customer record. For export invoices, the buyer VAT number must be left out (BR-KSA-46).

The buyer is in Saudi Arabia but the address lacks a required field: street, building number, postal code, city, district or country. Complete the customer's national address; the postal code must be 5 digits (BR-KSA-67).

Correct the cause and submit it as a new document with its own UUID, invoice counter value, hash and time stamp. Do not reuse the rejected document's counter value; the new document's previous invoice hash is the hash of the document generated just before it.

Usually the chain is broken: the previous invoice hash points to the last accepted document instead of the last generated one, or a document was issued outside the integrated system. ZATCA records rejected documents' hashes too, so the chain must include them.

It is not listed in ZATCA's directory of e-invoicing solution providers. It integrates with Fatoora through your own onboarding: your unit passes ZATCA's compliance checks and receives its own production CSID before any invoice is cleared or reported.

See ZATCA's error codes on the invoice while it is still a draft. ERP HRM Solution's ZATCA e-invoicing clears standard invoices at issue, reports simplified ones in the background and shows every error and warning with its code.

Download PDF Printable A4 copy with sources and the last-verified date.

Bring your whole business into one place

Start your free 14-day trial today. Your workspace is ready in minutes.

Chat with AI