KSA v2: Error messages
Every error message the KSA ZATCA API v2 returns from the Unify API and EGS onboarding, grouped by area, with the request fields each one is about. This page documents API v2, a legacy version.
These are the error messages the Unify API and EGS onboarding return when a request does not pass validation. Messages are grouped by the part of the request they check. The Field column names the request fields each message is about. Where a message contains [document ID], the response shows the ID you sent.
Document level
| Message | Field |
|---|---|
| Document Id is missing! Please provide your invoice number here. | documentId |
| Document Id is not a number! Please provide your invoice number here. Remove any prefix if you have and only share the sequence number! | documentId |
| Issue Date is missing! | documentIssueDateTime |
| Document Issue Date is not provided in a valid format! Document Issue date should be in this ‘YYYY-MM-DD’ format! | documentIssueDateTime |
| Document Issue Date is in the future! Document Issue date must be less or equal to the current date! | documentIssueDateTime |
| Supply start date is mandatory when Supply end date is provided for any type of Invoice | supplyStartDate, supplyEndDate |
| Supply end date must be greater than Supply Start date | supplyStartDate, supplyEndDate |
| Currency is missing! Currency code should be in ISO 4217 code format! | currency |
| Currency code is wrong! Currency code should be in ISO 4217 code format! | currency |
| Document Currency is not ‘SAR’ and ‘vatCurrency’ field is empty. If document currency is other than SAR, ‘vatCurrency’ should be provided and it should be only ‘SAR’. | currency, vatCurrency |
| Document Currency is not ‘SAR’ and ‘vatCurrency’ is also not ‘SAR’. If document currency is other than SAR, ‘vatCurrency’ should be provided and it should be only ‘SAR’. | currency, vatCurrency |
| Payment means is missing! Payment means should be any of the following mode of payment: ‘CASH’, ‘CREDIT’, ‘PAYMENT_TO_BANK_ACCOUNT’, ‘BANK_CARD’, ‘OTHER’. | paymentMeans |
| VAT Currency must be SAR | vatCurrency |
| Reference Id is missing! Reference Id is required for credit/debit note! | referenceId |
| Note issuance reason is missing! Note issuance reason is required for credit/debit note! | noteIssuanceReason |
| All the document amounts and quantities must be positive. | lineItemPrice, lineItemQty, lineItemTaxableAmount, discountOnLineItem, vatRateOnLineItem, lineItemVatAmount, lineItemSubTotal, totalExcludingVat, totalTaxableAmountExcludingVat, vatTotal, documentTotal, discountOnDocumentTotal |
Invoice and transaction type
| Message | Field |
|---|---|
| Supply date is mandatory for B2B Invoice | supplyDate |
| Document Type is missing! | documentType |
| Special Billing status: Self Billed or Third Party should be either true or false! | isSelfBilled, isThirdParty |
| Special Transaction status: Export, Nominal, Summary should be true or false! | isNominalSupply, isExport, isSummary |
| Self Billing is not allowed for Export Invoices | isSelfBilled, isExport |
| Self Billing is not allowed for B2C Invoices and asscoiated Credit & Debit Notes | isSelfBilled |
| Special billing option is selected. But, Self-Billed or Third party type selection is missing. Please select one of the two Special billing options! | isSelfBilled, isThirdParty |
| Self Billing option is only allowed for Standard Tax Invoice(B2B)! | isSelfBilled |
| Only one Special Billing option is allowed at a time. Please select Self-Billed or Third party! | isSelfBilled, isThirdParty |
| Special transaction option is selected. But, Export or Summary or Nominal Supply type selection is missing. Please select one of the three Special transaction options! | isSummary, isNominalSupply, isExport |
| Export Billing option is only allowed for Standard Tax Invoice(B2B)! | isExport |
| If Invoice = B2C and Summay Invoice, Buyer Name is Mandatory | isSummary, buyerName, documentType |
| If Invoice = B2C and Summay Invoice, Supply start & End date are Mandatory | supplyStartDate, documentType, isSummary, supplyEndDate |
Buyer details
| Message | Field |
|---|---|
| Invalid Buyer ID, Could not find the same in Masters | BuyerId |
| Buyer VAT or Group VAT number is Mandatory for B2B Invoices & associated CDN or DBN other than Export Invoices | |
| If Buyer VAT numeber is Provided, it should be 15 digits & start and end with digit ‘3’ | |
| Buyer Address is empty! Please provide a valid Buyer address | BuyerAddress |
| If Buyer Group VAT numeber is Provided, it should be 15 digits & start and end with digit ‘3’ | |
| Buyer VAT or Group VAT Number should be blank for Export Invoices | |
| Buyer Address Line 1 is empty! Please provide Buyer address Line 1 | BuyerAddress, addrLine1 |
| Buyer Address Line 2 is empty! Please provide Buyer address Line 2 | BuyerAddress, addrLine2 |
| Buyer Address Additional Number is empty! Please provide Buyer address Additional Number | BuyerAddress, additionalNo |
| Buyer Address Additional Number should be a 4 digit number value! Please provide Buyer address Additional Number | BuyerAddress, additionalNo |
| Buyer Address Building Number is empty! Please provide Buyer address Building Number | buildingNo, BuyerAddress |
| Buyer Address Building Number should be a 4 digit number value! Please provide Buyer address Building number | BuyerAddress, buildingNo |
| Buyer Address city is empty! Please provide Buyer address city | BuyerAddress, city |
| Buyer Address state is empty! Please provide Buyer address state | BuyerAddress, state |
| Buyer Address zip code is empty! Please provide Buyer address zip code | BuyerAddress, zipCode |
| Buyer Address zip code should be a 5 digit number value! Please provide Buyer address zip code | BuyerAddress, zipCode |
| Buyer Address district is empty! Please provide Buyer address district | BuyerAddress, district |
| Buyer Address country is empty! Please provide Buyer address country | BuyerAddress, country |
| Invalid Buyer country code, please provide a valid 2 letter country code from ISO 3166 Alpha-2 list | BuyerAddress, country |
| The buyer identification must be only one of the scheme ID - NAT, IQA, PAS, CRN, MOM, MLS, SAG, GCC, OTH | BuyerId |
| If the tax exemption reason code = VATEX-SA- EDU or VATEX-SA-HEA, then the other buyer ID is mandatory and must be national ID = NAT | vatExemptionReasonCode, BuyerId |
| When Invoice = B2C or associated Credit or Debit Note, & the tax exemption reason code = VATEX-SA-EDU or VATEX-SA-HEA, then Buyer name is mandatory. | buyerName, vatExemptionReasonCode, documentType |
Seller details
| Message | Field |
|---|---|
| Seller name is empty! Please provide a valid Seller name (3 cleared and 1 warned) | SellerName |
| Seller Address is empty! Please provide valid Seller address | SellerAddress |
| Seller Address Line 1 is empty! Please provide valid data in Seller address Line 1 | SellerAddress, addrLine1 |
| Seller Address Line 2 is empty! Please provide valid data in Seller address Line 2 | SellerAddress, addrLine2 |
| Seller Address Additional Number is empty! Please provide a valid Seller address Additional Number | SellerAddress, additionalNo |
| Seller Address Additional Number should be a 4 digit number value | SellerAddress, additionalNo |
| Seller Address Building Number is empty! | SellerAddress, buildingNo |
| Seller Address Building Number should be a 4 digit number value | SellerAddress, buildingNo |
| Seller Address city is empty! Please provide Seller address city | SellerAddress, city |
| Seller Address state is empty! Please provide Seller address state | SellerAddress, city |
| Seller Address zip code is empty! Please provide Seller Address zip code | SellerAddress, zipCode |
| Seller Address zip code should be a 5 digit number value! Please provide Seller Address zip code | SellerAddress, zipCode |
| Seller Address district is empty! Please provide Seller address district | SellerAddress, district |
| Seller Address country is empty! Please select Seller address country from dropdown | SellerAddress, country |
| Invalid Seller country code, please provide a valid 2 letter country code from ISO 3166 Alpha-2 list | SellerAddress, country |
| The seller identification can only be one of the scheme ID - CRN, MOM, MLS, SAG, OTH, In case multiple IDs exist then one of the above must be entered following the sequence | sellerId |
| Invalid Seller ID, Could not find the same in Masters | sellerId |
Line items
| Message | Field |
|---|---|
| Line Item - At-least one line item should be added! | documentLineItems |
| Line Item ID is missing | lineItemId |
| Line Item ID length should not exceed 6 characters | lineItemId |
| Line item Description is missing for Line ID# | lineItemDescription, documentLineItems |
| Line item quantity is missing for line ID # | lineItemQty, documentLineItems |
| Line item quantity should be a number. Example: 10! | lineItemQty, documentLineItems |
| Line item discount is missing! | discountOnLineItem, documentLineItems |
| Line item discount should be a number. Example: 10.00! | discountOnLineItem, documentLineItems |
| Line item price is missing! | lineItemPrice, documentLineItems |
| Line item price should be a number. Example: 10.00! | lineItemPrice, documentLineItems |
| Line item sub total is missing! | lineItemSubTotal, documentLineItems |
| Line item sub total should be a number. Example: 10.00! | lineItemSubTotal, documentLineItems |
| Line item taxable amount is missing! | lineItemTaxableAmount, documentLineItems |
| Line item taxable amount should be a number. Example: 10.00! | lineItemTaxableAmount, documentLineItems |
| Line item vat amount is missing! | lineItemVatAmount, documentLineItems |
| Line item vat amount should be a number. Example: 10.00! | lineItemVatAmount, documentLineItems |
| Tax Category code is missing | vatCategoryCode, documentLineItems |
| Tax Exemption Reason code is mandatory when Tax Catogory code is E & Z | vatExemptionReasonCode, vatCategoryCode, documentLineItems |
| Line item vat rate is missing! | vatRateOnLineItem, documentLineItems |
| Line item vat rate should be a number. Example: 15.00! | vatRateOnLineItem, documentLineItems |
| When tax Category code is ‘Exempt’ or ‘Zero rated’, then Tax Exemption reason code is mandatory | vatExemptionReasonCode, vatCategoryCode, documentLineItems |
| Line item 1 quantity is zero or negative! | lineItemQty, documentLineItems |
| Line item 1 price is zero or negative! | lineItemPrice, documentLineItems |
| Line item 1 discount is negative! | lineItemPrice, documentLineItems |
| Line item 1 LineItemtaxable amount is negative! | lineItemTaxableAmount, documentLineItems |
| Line item 1 lineItemTaxableAmount calculation is incorrect. lineItemTaxableAmount should be rounded to two decimal digits using the Half-Up Rule after calculation. lineItemTaxableAmount = (lineItemPrice - discountOnLineItem)*lineItemQty | lineItemTaxableAmount, documentLineItems |
| Line item 1 lineItemVatAmount calculation is incorrect. lineItemVatAmount should be rounded to two decimal digits using the Half-Up Rule after calculation. lineItemVatAmount = lineItemTaxableAmount*vatRateOnLineItem | lineItemVatAmount, documentLineItems |
| Line item 1 lineItemSubTotal calculation is incorrect. lineItemSubTotal should be rounded to two decimal digits using the Half-Up Rule after calculation. lineItemSubTotal = lineItemTaxableAmount+lineItemVatAmount | lineItemSubTotal, documentLineItems |
| Line Item VAT Amount & Line Item Subtotal are Mandatory for a Tax Invoice | lineItemSubTotal, lineItemVatAmount, documentLineItems |
Document summary
| Message | Field |
|---|---|
| Total excluding vat is missing! | totalExcludingVat |
| Total excluding vat should be a number. Example: 120.00! | totalExcludingVat |
| Total Taxable Amount excluding vat is missing! | totalTaxableAmountExcludingVat |
| Total Taxable Amount excluding vat should be a number. Example: 220.00! | totalTaxableAmountExcludingVat |
| Vat total is missing! | vatTotal |
| Vat total should be a number. Example: 220.00! | vatTotal |
| Document total is missing! | documentTotal |
| Document total should be a number. Example: 220.00! | documentTotal |
| Discount on document total is missing! | discountOnDocumentTotal |
| Discount on Document total should be a number. Example: 220.00! | discountOnDocumentTotal |
| totalExcludingVat calculation is incorrect. Please check this calculation(totalExcludingVat should be rounded to two decimal digits using the Half-Up Rule after calculation)! totalExcludingVat = lineItemsTaxableAmountTotal-discountOnDocumentTotal | discountOnDocumentTotal, totalExcludingVat, lineItemTaxableAmountTotal |
| totalTaxableAmountExcludingVat calculation is incorrect. Please check this calculation(totalTaxableAmountExcludingVat should be rounded to two decimal digits using the Half-Up Rule after calculation)! totalTaxableAmountExcludingVat = lineItemsTaxableAmountTotal | totalTaxableAmountExcludingVat, lineItemTaxableAmountTotal |
| vatTotal calculation is incorrect. Please check this calculation(vatTotal should be rounded to two decimal digits using the Half-Up Rule after calculation)! vatTotal = (lineItemsTaxableAmountTotal-discountOnDocumentTotal)*documentVatRate | vatTotal, lineItemTaxableAmountTotal, discountOnDocumentTotal, documentVatRate |
| documentTotal calculation is incorrect. Please check this calculation(documentTotal should be rounded to two decimal digits using the Half-Up Rule after calculation)! documentTotal = totalExcludingVat+vatTotal | documentTotal, vatTotal, totalExcludingVat |
| discountOnDocumentTotal is negative! | discountOnDocumentTotal |
| Invoice Should have Amount due for Payment | |
| Invoice Should have Amount Paid |
Decimal places
| Message | Field |
|---|---|
| Document level allowance should contain only 2 decimal values | |
| Sum of Invoice line net amount should contain only 2 decimal values | |
| Invoice Taxable amount should contain only 2 decimal values | totalTaxableAmountExcludingVat, lineItemTaxableAmount, lineItemTaxableAmountTotal |
| Sum of Allowances of document level should contain only 2 decimal values | |
| Invoice Total with VAT should contain only 2 decimal values | |
| Invoice total VAT should contain only 2 decimal values | |
| Total paid amount should contain only 2 decimal values | |
| Amount due for payment should contain only 2 decimal values | |
| Invoice line net amount should contain only 2 decimal values | |
| Line Discount should contain only 2 decimal values | discountOnLineItem |
| Line net Price should contain only 2 decimal values | lineItemSubTotal |
Duplicate documents
| Message | Field |
|---|---|
| This document with ID - [document ID] is already present with a different document type in the system! Re-using the same document ID for different document types is not allowed. | documentId |
| This Document number: [document ID] is already reported with ZATCA successfully! Please do not try to report this document again. Re-reporting is not allowed. | documentId |
| This Document number: [document ID] is already cleared with ZATCA successfully! Please do not try to report this document again. Re-clearing is not allowed.) | documentId |
EGS onboarding (CSR request)
| Message | Field |
|---|---|
| OTP is mandatory field | OnBoarding, OTP |
| OTP is not a number | OnBoarding, OTP |
| OTP should be a 6 digit number | OnBoarding, OTP |
| Common name is a mandatory field | OnBoarding, Common Name |
| Serial number is a mandatory field | OnBoarding, serialNumber |
| Invalid serial number, serial number should be in regular expression format (1-…|2-…|3-…) | OnBoarding, serialNumber |
| Organization identifier/Seller VAT or Group VAT Number is a mandatory field | OnBoarding, organizationIdentifier |
| Invalid organization identifier, please provide a valid 15 digit vat number | OnBoarding, organizationIdentifier |
| Invalid organization identifier, If seller VAT number is provided, it should be starting and ending with digit 3 | OnBoarding, organizationIdentifier |
| Invalid organization identifier, If Seller Group VAT Number is provided, it should be starting and ending with digit ‘3’ an d 11 digit should be ‘1’ | OnBoarding, organizationIdentifier |
| Organization unit name is a mandatory field. Please provide your branch name. | OnBoarding, organizationUnitName |
| Invalid organization unit name. You provided a group VAT number for organizationIdentifier. Please provide your valid 10 digit of your individual group tin number here | OnBoarding, organizationUnitName |
| Organization name is a mandatory field. Please provide your company name here. | OnBoarding, organizationName |
| Country code is a mandatory field | OnBoarding, countryName |
| Invalid country code, please provide a valid 2 letter country code from ISO 3166 Alpha-2 list | OnBoarding, countryName |
| Invoice type is a mandatory field | OnBoarding, invoiceType |
| Invalid invoice type, please provide a valid invoice type. Refer to the API documentation for sample data and related explanation. | OnBoarding, invoiceType |
| Location is a mandatory field | OnBoarding, location |
| Invalid Location, please provide a valid Location without any numbers or special characters! | OnBoarding, location |
| Industry is a mandatory field | OnBoarding, industry |
| Invalid Industry, please provide a valid Industry without any numbers or special characters! | OnBoarding, industry |