العربيةSign inStart free trial
Sign inStart free trial

Error messages: e-invoicing (ZATCA)

Every message you may see when you set up ZATCA e-invoicing, send invoices to ZATCA or fix a rejected document, and what to do.

ReferenceUpdated

Start a free trial

These messages appear in Settings → E-invoicing (ZATCA), on the e-invoice panel of an invoice and in the e-invoices list. Messages that start with a code such as BR-KSA-40 come from the check the system runs before it sends a document to ZATCA: the code is shown next to the message. A "…" stands for a name, a number or a code that the message fills in.

Tip

After you correct a branch, a customer or a tax rule, open the invoice and press Correct and send as a new document. The system builds the document again with the new details and sends it.

Setting up a device

Message What to do
This branch is not in a country with ZATCA e-invoicing Only branches in Saudi Arabia use e-invoicing devices. Add the device to a Saudi branch.
Choose at least one type The device has no document type. Choose standard, simplified or both.
Use 1100, 1000 or 0100 The document types chosen for the device are not allowed. Pick them again from the list.
Six digits from the Fatoora portal The one-time password must be 6 digits. Copy it from the Fatoora portal.
The OTP must be the 6 digits from the Fatoora portal The one-time password is not 6 digits. Copy the 6 digits from the Fatoora portal; a code works for one hour.
The branch details are not ready for a certificate request Some seller details of the branch are missing; the message lists them. Complete them in Settings → Branches, then request again.
This branch is in a VAT group: enter the member's 10-digit TIN as the organisation unit The branch's VAT number belongs to a VAT group (its 11th digit is 1). In Add a device, type the member's 10-digit TIN in Organisation unit.
For a VAT group the organisation unit must be the member's 10-digit TIN Listed under The branch details are not ready …: the device has no valid TIN. Delete it and add it again with Organisation unit filled.
ZATCA did not issue a compliance certificate (…) ZATCA refused the one-time password or the request, and the device shows Problem. Check that the code is less than one hour old and from the same environment, then try with a new code.
Request the compliance certificate first The compliance checks need the compliance certificate. Do the one-time password step first.
Run the compliance checks first; all of them must pass The production certificate is only issued after every check passes. Press Run the checks until all pass.
ZATCA did not issue the production certificate (…) ZATCA refused the production request, and the device shows Problem. Press Onboard to try again, and read ZATCA's messages under the device.
This device is already onboarded; use renewal The device is ready, so it does not need onboarding again. Use Renew certificate when the certificate is close to its end.
Only an onboarded device can be renewed The device has not finished onboarding. Onboard it first.
ZATCA did not renew the certificate (…) ZATCA refused the renewal. A ready device stays ready. Get a new one-time password in Fatoora for renewing the existing cryptographic stamp, then renew again.
A device can only be changed before onboarding starts Onboarding has started, so the device stays as it is. Add a new device instead.
This device has signed e-invoices; revoke it instead of deleting it A device that signed documents is kept for the record. Press Revoke instead of deleting it.
Device not found The device, or a remembered device in My account, no longer exists. Refresh the list.

Sending to ZATCA and ZATCA's answers

Message What to do
The branch has no onboarded e-invoicing device yet The invoice's branch has e-invoicing on but no ready device. Add and onboard one in Settings → E-invoicing (ZATCA).
The e-invoicing device is not onboarded The branch's device has no production certificate. Finish its onboarding, then send again.
This invoice's branch does not use e-invoicing The branch is not in Saudi Arabia, or its e-invoicing was off when the invoice was issued (it is not an e-invoice). Nothing needs to be sent.
E-invoices need a currency with 2 decimals; this booking is in … The booking is in a 3-decimal currency such as BHD, KWD or OMR. At an e-invoicing branch, sell in a 2-decimal currency such as SAR.
Amounts must have at most two decimals for ZATCA (found … …) An amount has more than 2 decimals. Use amounts with 2 decimals at most, then correct and send again.
No exchange rate from … to SAR for the VAT total in SAR The invoice is not in SAR and the VAT total must also be given in SAR. Add a rate to SAR in Settings → Currencies.
The invoice has no tax breakdown The invoice has no tax details. Issue the invoice again.
The invoice lines have no tax categories (issued before tax rules were in place) The invoice is older than your tax rules. Issue a credit note and a new invoice.
The document does not pass the local validation The check before sending found problems; they are listed with their codes. Fix each one, then press Correct and send as a new document.
ZATCA answered … ZATCA had a temporary problem. The system retries by itself; you can also press Send again now.
ZATCA refused the device credentials (…) The device's certificate is not valid or has expired. The device shows Problem and stops signing: another ready device of the branch signs, or documents wait. Press Renew certificate or Onboard again.
ZATCA rejected the document ZATCA listed its reasons under the document. Correct the data, then press Correct and send as a new document.
ZATCA rejected this document: correct the data and regenerate it as a new document A rejected document cannot be sent again as it is. Correct the data, then press Correct and send as a new document.
ZATCA reports a conflict with an earlier submission (409) The same document was sent before. Check it in the Fatoora portal, and send it as a new document if needed.
ZATCA has already accepted this document The document is already cleared or reported. Nothing to do.
Only rejected or failed e-invoices can be regenerated The document is waiting or accepted. Wait, or press Send again now if it is waiting.
There is nothing to regenerate The invoice has no e-invoice yet. Press Create and send.
XML not found This file does not exist for the document, for example the cleared copy of a simplified invoice. Download the Signed XML instead.

Your seller details (the branch)

Correct these in Settings → Branches, then send the document again.

Message What to do
BR-06 The seller name (BT-27) is missing The branch has no legal name. Add it.
BR-KSA-08 The seller identification (BT-29, e.g. the CR number) is missing The branch has no commercial registration number. Add it.
BR-KSA-08 The seller identification must use CRN, MOM, MLS, 700, SAG or OTH and contain only letters and digits The registration number has spaces or symbols, or the wrong type. Type it with letters and digits only.
BR-KSA-09 The seller address is missing: … The branch address is incomplete; the message names the missing parts. Complete them.
BR-KSA-09 The seller address has no additional number (PlotIdentification) A warning: the branch has no additional number. Add the 4-digit additional number of the national address.
BR-KSA-37 The seller building number must be 4 digits Type the branch's 4-digit building number.
BR-KSA-66 The seller postal code must be 5 digits Type the branch's 5-digit postal code.
BR-KSA-39 The seller VAT number (BT-31) is missing The branch has no VAT number. Add it.
BR-KSA-40 The seller VAT number must be 15 digits starting and ending with 3 The branch's VAT number is not in the Saudi format. Correct it.
KSA-14 The QR code is longer than 700 characters The QR code holds the seller name, so a very long legal name makes it too long. Shorten the branch's legal name.

Your customer's details (the buyer)

Correct these on the customer's page, then send the document again.

Message What to do
BR-KSA-42 The buyer name (BT-44) is required on a standard tax invoice Add the customer's name.
BR-KSA-81 A standard tax invoice needs the buyer's VAT number or another buyer id (BT-46) Add the customer's VAT number, or another id such as the commercial registration.
BR-KSA-44 The buyer VAT number must be 15 digits starting and ending with 3 The customer's VAT number is not in the Saudi format. Correct it.
BR-CUSTOM-VALIDATION-01 The buyer VAT number must not be the seller's The customer has your own VAT number. Correct the customer's VAT number.
BR-KSA-14 The buyer id must use one of TIN, CRN, MOM, MLS, 700, SAG, NAT, GCC, IQA, PAS, OTH and contain only letters and digits The customer's id type or number is not valid. Choose a listed type and type the number with letters and digits only.
BR-KSA-10 The buyer address is missing: … A tax invoice needs the customer's full address. Complete the parts the message names.
BR-KSA-63 A Saudi buyer address needs: … A Saudi customer needs street, building number, postal code, city and district. Complete them.
BR-KSA-67 A Saudi buyer postal code must be 5 digits Correct the customer's postal code.
BR-KSA-46 An export invoice must not carry the buyer's VAT number or id Remove the customer's VAT number and id, or switch off the export option on the branch.
BR-KSA-25 Private education or healthcare to citizens needs the buyer name Add the customer's name.
BR-KSA-49 Private education or healthcare to citizens needs the buyer's national id (NAT) Set the customer's id type to national id and add the number.
BR-KSA-71 A simplified summary invoice needs the buyer name Add the customer's name.

Tax rules and invoice lines

Tax rules are in Settings → Taxes.

Message What to do
BR-16 The invoice must have at least one line The booking has no items. Add items to the booking, then issue the invoice.
BR-25 Line …: the item name is missing An item has no description. Add one on the booking.
BR-KSA-F-04 Line …: the quantity must be positive or … must not be negative A quantity or an amount is zero or negative. Check the booking's items.
BR-KSA-18 Line …: the VAT category must be S, Z, E or O The line's tax rule has no valid category. Correct the tax rule.
BR-KSA-11 Line …: the VAT rate must be 0 for category … A zero-rated, exempt or out-of-scope rule has a rate. Set its rate to 0.
BR-S-05 Line …: a standard-rated line needs a rate above 0 A standard-rate rule has 0%. Set the right rate.
BR-KSA-DEC-02 Line …: the VAT rate has more than two decimals Set the tax rule's rate with 2 decimals at most.
BR-KSA-CL-04 The … breakdown needs a VAT exemption reason code (BT-121) A zero-rated, exempt or out-of-scope rule has no exemption reason. Choose the reason on the tax rule.
BR-KSA-83 The … breakdown needs the exemption reason text (BT-120) Add the exemption reason text on the tax rule.
BR-KSA-23, BR-KSA-69 or BR-KSA-24 … is not a valid reason code for category … The exemption reason belongs to another category. Choose a reason of the rule's own category.
BR-S-10 A standard-rated breakdown must not have an exemption reason Remove the exemption reason from the standard-rate rule.

Dates

Message What to do
BR-KSA-04 The issue date (BT-2) must not be in the future The invoice date is later than today. Contact support so they check the date.
BR-KSA-15 A standard tax invoice must contain the supply date (KSA-5) The supply date comes from the trip's departure. Check the trip's dates.
BR-KSA-35 A supply end date needs a supply date Check the trip's departure and return dates.
BR-KSA-36 The supply end date must not be before the supply date The trip returns before it departs. Correct the trip's dates.
BR-KSA-72 A simplified summary invoice needs the supply date and end date Check the trip's departure and return dates.

Document type, branch options and notes

Message What to do
Self-billing is not allowed on export invoices (BR-KSA-07) The branch has both export and self-billing on. Switch one off.
BR-KSA-07 Self-billing is not allowed for export invoices Switch off export or self-billing on the branch.
BR-KSA-31 Simplified documents may only be third party, nominal or summary Simplified invoices cannot be export or self-billed. Switch these options off on the branch.
BR-KSA-06 The invoice transaction code (KSA-2) must be 01 or 02 followed by five 0/1 flags The branch's document options are not valid. Check them, then send again.
BR-KSA-05 The invoice type code (BT-3) must be 388, 381 or 383 An internal check failed. Correct and send as a new document; contact support if it comes back.
BR-KSA-17 A credit or debit note must state its reason (KSA-10) Write the reason when you issue the note.
BR-KSA-56 A credit or debit note must reference the original invoice (BT-25) Issue the note from the original invoice.
BR-KSA-16 The payment means code must be 10, 30, 42, 48 or 1 The invoice carries a payment means ZATCA does not accept. New invoices of e-invoicing branches always get an allowed code (cheque, customer credit, points and other methods become 1, not defined), so this only affects older invoices: press Correct and send as a new document.

Technical checks

These come from checks on the document's structure, totals, signature and chain. Press Correct and send as a new document. If the same message comes back, contact support and give them the code.

Message What to do
BR-02 The invoice number (BT-1) is missing Correct and send as a new document.
BR-CO-10 The sum of line net amounts (BT-106) must equal the lines The totals do not add up. Correct and send as a new document; contact support if it repeats.
BR-CO-13 The total without VAT (BT-109) must be lines − allowances + charges The totals do not add up. Correct and send as a new document; contact support if it repeats.
BR-CO-14 The VAT total (BT-110) must be the sum of the breakdown The totals do not add up. Correct and send as a new document; contact support if it repeats.
BR-CO-15 The total with VAT (BT-112) must be the total without VAT + VAT The totals do not add up. Correct and send as a new document; contact support if it repeats.
BR-CO-16 The amount due (BT-115) must be the total with VAT − prepaid + rounding The totals do not add up. Correct and send as a new document; contact support if it repeats.
BR-CO-18 The breakdown … …% has no lines A tax group has no lines. Correct and send as a new document.
BR-S-08 The taxable amount of … …% must equal the sum of its lines Correct and send as a new document; contact support if it repeats.
BR-S-09 The VAT of … …% must be the taxable amount × rate, rounded on the document Correct and send as a new document; contact support if it repeats.
BT-114 The payable rounding amount may only absorb one minor unit per tax category Correct and send as a new document; contact support if it repeats.
BR-KSA-50 Line …: the line VAT differs from net × rate A warning about rounding. The document is still sent; nothing to do.
BR-KSA-51 Line …: the amount with VAT must equal net + VAT Correct and send as a new document.
BR-KSA-52 Line …: the line VAT amount and amount with VAT are required Correct and send as a new document.
BR-KSA-EN16931-11 Line …: quantity × price must equal the net amount Correct and send as a new document.
BR-DEC … is not a number or … has more than two decimals An amount is not valid. Use a 2-decimal currency, then correct and send as a new document.
BR-KSA-CL-01 The invoice currency (BT-5) must be an ISO 4217 code Correct and send as a new document.
BR-KSA-CL-02 … has currency …; all amounts must be in … except the VAT total in SAR Correct and send as a new document.
BR-KSA-68 The tax currency code (BT-6) must be SAR Correct and send as a new document.
BR-KSA-EN16931-08 Exactly one tax total with subtotals must be given Correct and send as a new document.
BR-KSA-EN16931-09 Exactly one tax total without subtotals (the VAT in SAR) must be given Correct and send as a new document.
BR-KSA-EN16931-01 Business process (BT-23) must be "reporting:1.0" Correct and send as a new document.
BR-KSA-F-01 The issue date must be YYYY-MM-DD Correct and send as a new document.
BR-KSA-70 The issue time (KSA-25) must be hh:mm:ss Correct and send as a new document.
BR-KSA-03 The UUID (KSA-1) must contain only letters, digits and dashes Correct and send as a new document.
BR-KSA-33 The invoice counter value (KSA-16) is missing or not digits Correct and send as a new document.
ICV The counter value is …, expected … The document is out of order in the device's chain. Correct and send as a new document.
BR-KSA-61 The previous invoice hash (KSA-13) is missing or not a base64 SHA-256 Correct and send as a new document.
PIH The previous invoice hash does not continue this device's chain The document does not follow the device's last document. Correct and send as a new document.
BR-KSA-27 The QR code (KSA-14) is missing or The QR code is not a valid base64 TLV Correct and send as a new document.
QR-1 to QR-5, QR-9 QR tag … is not … The QR code does not match the document. Correct and send as a new document.
BR-KSA-60 A simplified document must carry the cryptographic stamp The document was not signed. Check that the branch's device is ready, then correct and send again.
KSA-15 The cryptographic stamp (signature) is missing Check that the branch's device is ready, then correct and send again.
SIGNATURE … (the signature, hash or certificate problem) The signature does not match the document or the device's certificate. Renew the certificate, or onboard the device again.
UBL The root must be a UBL 2.1 Invoice Correct and send as a new document.
XML The XML is not well formed Correct and send as a new document; contact support if it repeats.

Related articles