You connect your system to the Fatoora platform, issue an invoice, and wait for it to be accepted. Instead of a clean response, you get back a rejection carrying error code 1009 and a message saying the VAT rate is incorrect. The message is short, but it hides one of the most common reasons for rejection in e-invoicing: the VAT rate applied is not consistent with the tax category declared on the invoice.
This guide is dedicated to a single error: error code 1009. We will explain exactly what it means, why the Zakat, Tax and Customs Authority (ZATCA) returns it, how to uncover the real cause behind it, how to fix it for good, and how to prevent it from recurring before the request ever reaches the platform. This page is part of the ZATCA e-invoicing errors guide, and specifically within the family of business-rule validation errors, because error 1009 is not a structural error in the XML file, but a logical and arithmetic error in the content of the invoice.
What does error code 1009 mean?
Error 1009 means that the VAT rate applied to a line item, or to the invoice as a whole, does not match the value expected under the declared tax category. To put it more clearly: you declared a certain tax category on the invoice, but the numeric rate you applied does not align with that category.
E-invoicing in the Kingdom does not look at the rate number on its own. It links two things together: the tax category code (TaxCategory) and the tax rate (Rate). The correct standard rate is 15% since 1 July 2020. But the presence of the number 15 alone is not enough. It must be paired with the standard category, and it must produce a tax amount equal to the rate multiplied by the taxable base. Any break in this three-way chain produces error 1009.
The Kingdom applies three main tax treatments, each with its own category code and specific rate:
- The standard category (Standard) with code
S: the rate is 15%, and it applies to most goods and services. - The zero-rated category (Zero-rated) with code
Z: the rate is 0%, and it applies to exports outside the GCC states, international transport, and certain qualifying goods. - The exempt category (Exempt) with code
E: it is not subject to tax, and it covers specific financial services and the lease of residential real estate.
Error 1009 appears when the relationship between this category and its associated rate breaks. The rule is simple at its core: each category has its own rate, and you may never mix the rate of one category with the code of another.
| Category | Rate |
|---|---|
| S (taxable) | 15% |
| Z (zero-rated) | 0% |
| E (exempt) | No tax |
How the platform returns error 1009 in the response
When the platform rejects an invoice because of an incorrect VAT rate, it returns a structured response containing the code, the message, and the affected field. Read it from top to bottom to know exactly which line item caused the rejection. This is a simplified example of a rejection response with error 1009:
The field status confirms that the invoice was rejected. The field code carries error code 1009. The field target points to the exact position within the invoice that carried the wrong rate, which here is the rate field inside the tax category classified on one of the line items. The field details is the most important: it tells you that the declared category is standard, so the rate must be 15, but the rate received was 5. This conflict is the essence of error 1009.
Do not ignore the targetfield. It is your direct guide to the line item that must be corrected, especially in an invoice that contains many line items with different categories. When you read the path, you learn whether the error is at the level of a single line item or at the level of the total tax on the invoice.
The four common causes behind error 1009
Error 1009 results from four recurring patterns. Each pattern has a different cause and a different fix. Diagnosing the right pattern saves you hours of random trial and error.
1. Using a rate other than 15% for the standard category
This is the most common cause. The system declares the standard category on the line item, but it applies an old or wrong rate such as 5%. The usual cause is an old setting that was never updated after the rate was raised to 15% in July 2020, or a value hard-coded manually in an invoice template that was never reviewed.
Remember that the standard rate in the Kingdom is 15% since 1 July 2020, and before that it was 5%. Any system still using 5% for the standard category runs into error 1009 on every invoice. The fix is to update the default rate value in the tax settings to 15%.
2. The tax category does not match the applied rate
Here the problem is not in the number itself, but in the pairing. A common example: an exempt line item (category E) that nonetheless carries a rate of 15%, or a zero-rated line item (category Z) that also carries a rate of 15%. The logic is broken: the exempt category carries no positive rate, and the zero category must carry a rate of 0, nothing else.
This often happens when the category code is chosen from a dropdown while the rate is calculated from a separate setting that did not sync with the category. The result is an invoice that declares one category and applies the rate of another. The fix is to link the category and the rate in a single source so they change together.
| Common mistake | Correct |
|---|---|
| E with 15% | E with no tax |
| Z with 15% | Z at 0% |
| S with 5% | S at 15% |
3. Wrong classification of a zero-rated or exempt line item
Sometimes the error is in the classification itself, before the rate. A line item that is actually subject to the standard rate is wrongly classified as zero-rated or exempt, or the reverse. This is not an arithmetic error but an error in understanding the tax treatment of the good or service.
The difference between zero-rated and exempt is subtle and important. Zero-rated is subject to tax but at 0%, and it stays within the tax return with the right to deduct input tax. Exempt is not subject to tax at all and does not allow input-tax deduction. Mixing the two confuses the return and triggers error 1009 when the rate is not consistent with the category. The fix is to review the correct classification for each item and fix it on the item card.
4. The tax amount does not equal the rate multiplied by the taxable base
The category may be correct and the rate correct, but the calculated tax amount does not match the result of the expected equation. The tax amount must equal the rate multiplied by the taxable amount. Any difference, even by a single halala, may be read as an incorrect rate.
The hidden cause behind this pattern is rounding. Calculating tax at the level of each individual line item and then summing the results may give a total that differs slightly from calculating tax at the level of the aggregated category. The fix is to unify the calculation methodology: calculate tax at the level of the aggregated category, and use a precise decimal type in the calculation rather than a floating type that loses precision on rounding.
A full example: a multi-category invoice rejected with error 1009
The clearest way to understand error 1009 is to trace a real invoice from its beginning until its rejection. Imagine a business selling three line items on a single invoice: an electronic device subject to the standard rate, an export shipment outside the GCC states that is zero-rated, and a specific financial service that is exempt. This is a sound invoice in concept, but a single error in the pairing is enough to reject it entirely.
Suppose the business prepared the line items as follows before sending:
The first line is correct: a standard category at 15% with a tax amount that matches the equation. But the second and third lines are wrong. The second line is zero-rated, so its rate must be 0% and its tax amount zero, not 15% and 750 riyals. The third line is exempt, so it carries no positive rate at all. When this invoice reaches the platform, it returns a rejection with error 1009 that points, through the field target , to the two broken lines, not to the sound line.
The correct fix is not to adjust the rate alone, but to reconsider the pairing. The second line must become a 0% rate with a zero tax amount while keeping the category Z. The third line must leave the tax equation entirely because it is exempt. After correction, the invoice becomes as follows:
The lesson from this example is that error 1009 does not necessarily mean an error in the entire invoice. It is often one or two line items, and the rest is sound. So you always start from the field target to know which line item to fix, instead of rebuilding the invoice from scratch.
Error 1009 in credit and debit notes
Error 1009 is not limited to invoices. It also appears in credit and debit notes, and here it is more deceptive. When you issue a credit note to correct a previous invoice, the VAT rate on the note must carry the same category and rate as the original invoice. A credit note for a standard invoice at 15% must itself carry a standard category and a 15% rate, not a different category.
The common mistake here is that the credit note is created from a separate template that does not inherit the category and rate from the original invoice. So if the note carries a rate that does not match its category, the operation is rejected with error 1009 exactly like any invoice. The fix is to derive the category and rate of the note from the original document it corrects, rather than entering them manually anew.
Remember too that a credit or debit note must carry a reference to the original invoice. When this reference matches, it becomes easy for your system to inherit the correct category and rate automatically, so the risk of error 1009 in notes disappears at its roots.
The relationship between error 1009 and the tax return
The importance of error 1009 goes beyond the acceptance of a single invoice. The rate and category on every invoice later aggregate into your periodic tax return. When line items are classified wrongly, the impact is not limited to the rejection of the invoice; it extends to the accuracy of the return itself.
A standard invoice feeds the box for sales subject to the standard rate in the return. A zero-rated invoice feeds the box for zero-rated sales. An exempt invoice feeds the box for exempt sales. The mixing of categories that triggers error 1009 at the invoice level also confuses the distribution of sales across the return boxes. So fixing error 1009 at its source is not merely a solution to a technical rejection, but a guarantee of a correct tax return when the time comes to file it with the Authority.
This explains why we insist on deriving the rate from the category in a single source. When the category is correct from the start, the invoice is accepted and the return is accurate, without double work or later adjustments. Accuracy at the point of issuance yields accuracy at the point of filing.
Errors confused with error 1009
Before you start fixing, make sure the rejection is really because of the VAT rate and not because of a neighboring error that is easily confused with error 1009. Three errors are close to it:
- VAT number format error: the invoice may be rejected because the seller’s VAT number does not follow the correct pattern, not because the rate is wrong. This is a different rejection with a different code, so do not waste time reviewing the rate.
- Conditional-existence error for the exemption reason: an exempt line item must carry the exemption reason as an accompanying field. Its absence triggers a rejection that seems related to the category but is in fact a missing field, not a wrong rate.
- Invoice-level arithmetic-consistency error: when the invoice total does not match the sum of the line items, an arithmetic rejection arises that may be confused with a rate error. Read the field
targetto tell them apart.
A careful reading of the rejection code and its message prevents hours of work in the wrong direction. Error 1009 specifically means a rate that is not consistent with its category, or a tax amount that does not match its equation, no more and no less.
How to diagnose the cause in steps
When a rejection with error 1009 reaches you, follow a fixed methodology instead of guessing:
- Read the field
targetto determine whether the error is on a single line item or on the invoice total. - Open the affected line item and look at the tax category code declared in it: is it
SorZorE? - Compare the applied rate with the correct rate for the category: standard equals 15%, zero-rated equals 0%, exempt has no positive rate.
- Verify the arithmetic equation: does the tax amount equal the rate multiplied by the taxable amount?
- If the category and rate are sound and the equation is broken, then the problem is in the rounding or in the summing methodology.
These five steps cover all four patterns. You usually find the cause in the second or third step, because most cases of error 1009 come back to pairing a category with a rate that does not belong to it.
When does error 1009 appear in Phase One and Phase Two
The way error 1009 appears differs between the two phases of e-invoicing. In Phase One, the generation phase, your system generates the invoice electronically without immediate integration with the platform. Here you do not receive a direct rejection response, but the wrong rate remains a latent defect in the stored invoice. When an audit comes or you move to Phase Two, these defects surface all at once.
In Phase Two, the integration phase, it becomes immediate. Every standard invoice between businesses is sent to the platform for clearance before it is delivered to the buyer, and every simplified invoice is reported within twenty-four hours. In this phase, the wrong rate does not pass silently. The response with error 1009 reaches you immediately, so the standard invoice is not delivered to the buyer until it is corrected.
This difference makes controlling the rate and category more urgent in Phase Two. What was a deferred defect in Phase One becomes an immediate barrier to completing the sale in Phase Two. That is why businesses moving to Phase Two suddenly discover a volume of error 1009 issues that were latent in their old settings without them noticing.
Configuration errors that produce error 1009 silently
Many cases of error 1009 do not arise from an error in a specific invoice, but from a wrong setting in the system that repeats on every invoice. Diagnosing the setting instead of the single invoice solves the problem at its root. The most prominent configuration errors:
- An old default rate: a general tax setting still at 5% from before July 2020, so every new item automatically inherits this wrong rate.
- A unified default category: the system set to assign the standard category to every item by default, so zero-rated or exempt items enter with a category that does not belong to them without the user noticing.
- Invoice templates with a fixed rate: an old template that carries a fixed rate value instead of deriving it from the item, so it applies the same rate to every line item however its category differs.
- Importing item data without a tax classification: uploading a list of items from an external file without a column for the tax classification, so the system takes an inaccurate default classification.
The common factor among these errors is that they are silent: they appear only when sending to the platform. A preventive check of the tax settings, once and carefully, is more useful than fixing each invoice individually. Review the default rate, the default category, the invoice templates, and the tax classification of every imported item before you begin sending for real.
How to fix error 1009 for good
The fix depends on the pattern you diagnosed. This is a summary of the solutions ordered by cause:
| Cause | Fix |
|---|---|
| A rate other than 15% for the standard category | Update the default rate to 15% in the tax settings |
| A category that does not match the rate | Link the category and rate in a single source that changes together |
| Wrong classification of a zero-rated or exempt item | Review the correct tax treatment and fix it on the item card |
| The tax amount does not match the equation | Calculate at the aggregated-category level with a precise decimal type |
The rule that ties all these solutions together is one: make the tax category, the rate, and the tax amount come from a single, consistent data source. When the rate is derived from the category automatically, and the tax amount is calculated from the rate automatically, error 1009 disappears at its roots because the conflict becomes impossible.
How to prevent error 1009 before it happens
Fixing after rejection is costly: a round trip with the platform for every invoice. It is better to prevent the error locally before building the final document. Build a simple validation layer inside your system that checks three things on every line item before sending:
- That the rate matches the declared category: standard equals 15, zero-rated equals 0, exempt has no positive rate.
- That the category code is from the approved list only:
SorZorE, no value outside it. - That the tax amount equals the rate multiplied by the taxable amount, within a rounding margin no greater than one halala.
Apply these three rules locally, and your invoice will not reach the platform unless it is free of rate errors. This approach turns error 1009 from a recurring rejection into a rare case that you catch before sending.
How Qoyod helps you
In Qoyod, the tax rate is derived automatically from the item’s category, so there is no room to mix a category with a rate that does not belong to it. You choose the tax classification for the item once on its card, and the system applies the correct rate automatically on every invoice: 15% for the standard category, 0% for zero-rated, and no tax for exempt.
Qoyod also calculates the tax amount at the aggregated-category level with decimal precision, so the rounding differences that trigger error 1009 do not arise. And before the invoice is sent to the Fatoora platform in Phase Two, Qoyod applies a local check of the consistency of the category, rate, and amount, so the invoice only reaches the Authority when it is compliant. You issue the invoice, and we handle the correctness of the rate and category.
Let the VAT rate be calculated correctly from the source
Qoyod links the item’s category to its correct rate, calculates tax with decimal precision, and verifies locally before sending. So you will not run into error 1009 in your invoices.
Where do you go after this guide?
Error 1009 is part of a wider system of e-invoicing errors. To understand its position and what it relates to:
- For the comprehensive reference to all invoicing errors: ZATCA e-invoicing errors.
- To understand the family of logical and arithmetic errors that error 1009 belongs to: business-rule validation errors.
- For the basics of VAT in the Kingdom, its rates and its categories: Value Added Tax.
- For Qoyod’s complete e-invoicing system: E-invoicing.
Read the target field
Inspect the declared category
Compare the rate
Verify the tax equation
Frequently asked questions
What is the correct standard VAT rate in the Kingdom?
The standard rate is 15% since 1 July 2020, after it had been 5%. Any line item in the standard category must carry a rate of exactly 15%, otherwise the invoice is rejected with error 1009. Updating the old setting from 5% to 15% resolves the most common cases of this error.
Why is my invoice rejected with error 1009 even though the rate is 15%?
Usually because the rate does not match the declared category, or because the tax amount does not equal the rate multiplied by the taxable amount. Check that the category code is standard, and that the tax amount is calculated at the aggregated-category level with decimal precision to avoid rounding differences.
What is the difference between the zero-rated category and the exempt category?
The zero-rated category is subject to tax at 0% and stays within the return with the right to deduct input tax. The exempt category is not subject to tax at all and does not allow this deduction. Mixing the two, or giving either of them a 15% rate, triggers error 1009.
How do I link the tax category to its rate to avoid the error?
Make the rate derived from the category code in a single data source instead of entering it manually. When you choose the category, the rate comes with it automatically: standard equals 15%, zero-rated equals 0%, exempt has no rate. This prevents the conflict at its roots.
Can I detect error 1009 locally before sending?
Yes, and this is the right approach. Apply three rules to every line item before building the document: the rate matches the category, the category code is from the approved list, and the tax amount equals the rate times the taxable amount. Qoyod applies this check automatically before sending.
Is rounding alone enough to trigger error 1009?
Yes, in some cases. Calculating tax on each line item and then summing may produce a total that differs by a halala from the expected value, so it is read as an incorrect rate. The solution is to calculate at the aggregated-category level using a precise decimal type rather than a floating one.
