Error Code 1016: Currency Not Supported

You connect your system to the Fatoora portal, issue an invoice, and wait for it to be accepted, but instead of a clean response you get a rejection carrying code 1016 and a message saying the currency is not supported. The message looks simple, yet it hides a precise cause behind it: e-invoicing in the Kingdom does not deal with any currency however it comes. It enforces strict rules on the document currency code, on the tax currency, and on the format in which the currency code is written in the XML file.

This guide is dedicated to one error only: error code 1016, currency not supported or invalid. We will explain exactly what it means, why the Zakat, Tax and Customs Authority returns it, how to uncover the real cause behind it, how to fix it permanently, and how to prevent it from recurring before the request even reaches the platform. This page is part of the guide to ZATCA e-invoicing errors, and specifically within the family of business rule validation errors, because code 1016 is not a structural error in the XML file so much as an error in a logical value the document carries: the currency code.

What does error code 1016 mean?

Code 1016 means the currency code declared in the invoice is not accepted by the e-invoicing system, either because it is not a recognized standard code, or because it does not match the currency required in the local context. E-invoicing does not look at the currency name as free text such as “Riyal” or “Dollar”; it deals with a standard three-letter code under the international standard ISO 4217, such as SAR for the Saudi riyal,USD for the US dollar, andEUR for the euro.

The invoice in the Kingdom carries two separate currency fields, both of which are subject to platform control:

• Document currency code (DocumentCurrencyCode): the currency in which the invoice values — price, amount, and total — are stated.
• Tax currency code (TaxCurrencyCode): the currency in which the VAT amount is calculated and declared.

The core rule that code 1016 guards is that the tax amount in local-market invoices must always be in Saudi riyals, that is TaxCurrencyCode equals SAR without exception. As for the document currency, it is expected to be SAR in a local transaction between a Saudi establishment and a customer inside the Kingdom, and a foreign currency is allowed only in specific cases such as export, provided the tax remains declared in riyals. Any departure from this chain produces code 1016.

How the platform returns code 1016 in the response

When the platform rejects the invoice because of the currency, the response comes back with a status indicating rejection, and inside it a list of validation errors, each carrying its code, its text, and the field that caused it. Below is a simplified sample of a response body carrying code 1016 as it might reach you from the Fatoora portal:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-KSA-EN16931-04",
        "category": "BUSINESS_RULES",
        "message": "Currency code is not supported or invalid",
        "qoyodCode": "1016",
        "targetField": "DocumentCurrencyCode"
      },
      {
        "type": "ERROR",
        "code": "BR-CL-01",
        "category": "BUSINESS_RULES",
        "message": "TaxCurrencyCode must be SAR for domestic invoices",
        "qoyodCode": "1016",
        "targetField": "TaxCurrencyCode"
      }
    ]
  },
  "reportingStatus": "NOT_REPORTED"
}

The field targetField is the starting line in every diagnosis: it tells you which currency field triggered the error. If it is DocumentCurrencyCode then the problem is in the invoice values currency, and if it is TaxCurrencyCode then the problem is in the declared tax currency. And the field message gives you the cause in readable form. Read the two together before you touch any setting.

The four common causes behind code 1016

Although the message is one, the source of the error varies. In practice, four causes recur more than the rest.

Cause one: a non-standard currency code or one in the wrong format

The most common cause is that the system sends a currency code that does not match ISO 4217. The system may have sent “SR” instead of SAR, or “﷼” as a text symbol, or “Riyal” spelled out, or even the currency code in lowercase sar while the standard expects three uppercase letters. The platform rejects all these values because they are not valid standard codes. The only accepted code for the Saudi riyal is SAR in exactly three uppercase letters.

Cause two: the tax currency is not in Saudi riyals

The document currency may be sound, but the tax currency TaxCurrencyCode was sent in another currency. This is a recurring error in export invoices: the invoice is drawn up in dollars, so TaxCurrencyCode is generated in dollars too by consequence. The rule does not accept that: in the local market, the tax amount and its currency must be in Saudi riyals even if the invoice values are in a foreign currency, because the tax return in the Kingdom is filed in riyals.

Cause three: a foreign currency in a local transaction

Sometimes an invoice is drawn up for a customer inside the Kingdom in a foreign currency, such as the dollar or the dirham, because of a wrong default setting on the customer card or in the branch settings. A local transaction between a Saudi establishment and a customer inside the Kingdom is expected to be drawn up in Saudi riyals. When a local invoice reaches the platform in a foreign currency without justification, it may be returned with code 1016.

Cause four: a conflict between the declared currency and the calculated amounts

In some cases the currency code is correct, but the amounts in the invoice are calculated in a currency different from the declared one, or the field TaxCurrencyCode differs from DocumentCurrencyCode without a tax exchange rate field linking them. This contradiction between what the invoice declares and the figures it carries pushes the platform to reject the document, because the standard requires full consistency between the declared currency, the values, and the tax currency.

Full example: an export invoice rejected with code 1016

Let us take a real case. A Saudi establishment sells a service to a customer outside the GCC countries, so it draws up the invoice in US dollars. The system generates the document and makes the tax currency a dollar too, so the platform rejects it. This is how the wrong values look against the expected values:

// What the system sent (rejected with code 1016)
DocumentCurrencyCode = "USD"
TaxCurrencyCode      = "USD"   // error: tax must be SAR
TaxAmount            = 150.00  // in dollars

// Expected under platform rules
DocumentCurrencyCode = "USD"   // allowed for export
TaxCurrencyCode      = "SAR"   // tax always in riyals
TaxAmount            = 0.00    // export is usually zero-rated
TaxExchangeRate      = 3.75    // tax exchange rate when needed

The central idea: the document currency may be foreign in export, but the tax currency stays SAR at all times. Whenever the tax is in a currency other than the riyal in a local invoice or an export invoice, expect code 1016.

The currency code under the ISO 4217 standard

The ISO 4217 standard is the internationally adopted list of currency codes, and every code in it consists of three uppercase Latin letters. E-invoicing follows this standard literally, so it does not accept local abbreviations or text symbols. These are examples of the most used correct codes:

• SAR: the Saudi riyal, which is the required code for the tax currency in all local invoices.
• USD: the US dollar, used in some export invoices for the document currency.
• EUR: the euro, in export transactions to the European market.
• AED: the UAE dirham, in some Gulf transactions depending on the transaction context.

The common mistake here is that the development team confuses the standard currency code with the typographic symbol such as “﷼” or “$”. The first is a data value sent to the platform, and the second is merely a visual display for the user. What reaches the platform must be the ISO 4217 code alone.

How the currency is actually written in the invoice file

The currency code does not appear in one place only inside the invoice file; it recurs in several fields that must all be consistent. The main currency field is the document currency code, which governs line-item values and totals. Then comes the tax currency code, which governs the tax groups and their amounts. Finally, some of the amount fields themselves carry a currency attribute accompanying each monetary value. The practical rule: the tax currency code and all tax amounts must point to the Saudi riyal in local invoices, while the document currency code follows the nature of the transaction.

When your system generates the file, make sure the currency attribute accompanying the total tax amount equals SAR, and that the currency attribute accompanying the invoice total equals the document currency code itself. Any difference between the currency attribute written next to an amount and the currency declared in the document header is enough on its own to trigger code 1016, because the platform reads each currency attribute separately and compares it with the declared currency.

The tax exchange rate when the document currency differs from the riyal

When an export invoice is drawn up in a foreign currency while the tax stays in riyals, a logical question arises: how does the platform link a value stated in dollars with a tax amount in riyals? The answer is the tax exchange rate field. This field carries the conversion rate of the document currency to the Saudi riyal at the time the invoice is issued, allowing the platform and the Authority to calculate the tax equivalent in riyals accurately.

Omitting the tax exchange rate when the document currency differs from the tax currency is a recurring cause of rejection. If you send an invoice with a foreign document currency and a tax currency in riyals without including the exchange rate linking them, the platform may reject the document for breaking the required consistency between the two currencies. The rule: whenever the document currency differs from the riyal, attach the correct tax exchange rate.

The impact of code 1016 on the entire invoice cycle

Code 1016 does not stop a single invoice only; it may disable the entire invoicing cycle if its source is a general setting. An invoice rejected in the simplified invoicing model remains without an approved fast response code, and an invoice rejected in the tax invoicing model is not approved by the platform, which means it is legally invalid for delivery to the customer. And as rejected invoices accumulate, reconciliation with the tax return at the end of the period becomes complicated. That is why the currency error deserves a root treatment from the setup, not patching invoice by invoice.

The good news is that the currency error is among the easiest errors to settle when treated at its source: one standard currency list, a tax currency fixed to the riyal, and local validation before sending. Three rules are enough to close the door on code 1016 for good.

Code 1016 in credit and debit notes

The credit note and the debit note are subject to the same currency rule. A credit note correcting an invoice drawn up in dollars must keep the same document currency as the original, and its tax currency must remain in Saudi riyals. Any difference in the document currency between the original invoice and its note, or any tax currency other than the riyal in the note, triggers code 1016 on the note exactly as it triggers it on the invoice.

The relationship of code 1016 to the tax return

The reason for the platform’s strictness regarding the tax currency is entirely logical: the tax return in the Kingdom is filed in Saudi riyals. If declaring tax in different currencies were allowed, it would be impossible to aggregate tax amounts in the return without unreliable conversion. That is why the platform requires the tax currency to be in riyals in every invoice, so that your data comes consistent with what you declare in your return. When you comply with this rule, your invoices match your return automatically, and you avoid differences that are hard to justify later.

Errors confused with code 1016

Before you start correcting, make sure you are treating the right error. There are codes that seem close but concern other fields:

• The tax rate error concerns the value of the rate and its category, not its currency, and it is a separate topic from code 1016.
• The line-item total error means that the sum of the line items does not match the total, and it is a calculation error unrelated to the currency.
• The XML structure error means that the field itself is missing or out of place, whereas code 1016 assumes the field exists but its value is rejected.

The practical difference: code 1016 is always about the value of the currency code, in the field DocumentCurrencyCode or TaxCurrencyCode. If the target field is other than these two, you are facing a different error.

How to diagnose the cause step by step

Follow a fixed sequence to reach the cause quickly instead of guessing:

• Read the target field targetField in the response to know whether it is the document currency or the tax currency.
• Inspect the sent code value: is it three uppercase letters from ISO 4217, or an abbreviation or a text symbol?
• Verify that TaxCurrencyCode equals SAR whatever the document currency is.
• Review the customer and branch setup: was a default foreign currency assigned to a local transaction without justification?

When code 1016 appears in phase one and phase two

In phase one (issuance and saving), some currency errors may not appear immediately because the invoice is not sent to the platform instantly. But in phase two (integration and connectivity), where the invoice is sent to the Fatoora portal before its approval or after its issuance, code 1016 appears in the response directly. That is why your system must apply currency validation locally before building the document, so that you do not discover the error too late in phase two.

Setup errors that produce code 1016 silently

Many cases of code 1016 do not come from an error in every invoice, but from a wrong setting that leaks into many invoices at once:

• A default foreign currency set at the company or branch level instead of the Saudi riyal.
• An old invoice template that sends the currency code as a local abbreviation such as “SR” instead of SAR.
• Deriving the tax currency from the document currency automatically instead of fixing it to the riyal.
• Importing customer data from a previous system that carries non-standard currency codes.

Fixing the setting at its source resolves dozens of invoices at once, instead of treating each invoice separately.

When a foreign currency is allowed and when the riyal is required

The greatest confusion around code 1016 revolves around the question: is a foreign currency allowed at all? The answer distinguishes between two fields. The document currency follows the nature of the transaction: in a local sale between a Saudi establishment and a customer inside the Kingdom the Saudi riyal is expected, and in an export to a customer outside the GCC countries a foreign currency such as the dollar or the euro is allowed depending on the commercial agreement. As for the tax currency, it does not follow the transaction at all; it stays the Saudi riyal in every case, because its reference is the tax return, not the commercial contract.

In short: the document currency may change according to the destination of the sale, but the tax currency is fixed to the riyal. Once you grasp this distinction, you avoid the most famous cause of code 1016, which is assuming the currency is one block that passes from the document to the tax by consequence.

A quick checklist before sending any invoice

Before your system builds the document and sends it to the platform, pass the invoice through this brief checklist. The invoice passing it successfully practically closes the door on code 1016:

• The document currency code is three uppercase Latin letters from the ISO 4217 list, not a local abbreviation or a text symbol.
• The tax currency code equals SAR exactly, whatever the document currency is.
• The currency attribute accompanying each tax amount equals the Saudi riyal.
• The local transaction is drawn up in Saudi riyals unless there is a clear export justification.
• When the document currency differs from the riyal, the tax exchange rate is attached and correct.
• The default currency setting at the company, branch, and customer level is reviewed and set to the riyal for the local market.

This checklist is not a one-time procedure, but a rule built into your system’s logic so that it applies to every invoice automatically. When you move from a manual check to a fixed programmatic validation, code 1016 becomes a memory, not a recurring event.

How to fix code 1016 permanently

The correction proceeds along two complementary tracks. The first is immediate to rescue the rejected invoice, and the second is fundamental to prevent the problem from recurring:

• Correct the currency code to a valid ISO 4217 code in three uppercase letters, so the riyal is SAR not “SR” and not “﷼”.
• Fix TaxCurrencyCode to SAR in every invoice, whether local or export.
• Make the currency of local transactions the Saudi riyal by default, and confine foreign currency to justified export cases.
• On export in a foreign currency, add the tax exchange rate that links the document currency to the riyal when needed.
• Reissue the corrected invoice and send it again, and make sure the response came back with acceptance not rejection.

How to prevent code 1016 before it happens

Prevention is cheaper than the cure. Put three protection layers in your system before any invoice reaches the platform:

• Local validation that rejects any currency code not matching the approved ISO 4217 list before building the document.
• A fixed rule that makes the tax currency the Saudi riyal whatever the document currency is.
• A default setting at the company level that makes the riyal the primary currency, with a clear exception for export.

How Qoyod helps you

In Qoyod, the currency code is derived from a standard list under ISO 4217, so there is no room to send a local abbreviation or an unacceptable text symbol. You choose the transaction currency from a unified list, and the system sends the correct three-uppercase-letter code automatically.

Qoyod also fixes the tax currency to the Saudi riyal in local-market invoices, so the tax currency does not slip into a foreign currency by consequence, even when the invoice values are drawn up in another currency in export. Qoyod supports multiple currencies in the transactions that call for it, while keeping the tax declared in riyals as the platform requires. And before the invoice is sent to the Fatoora portal in phase two, Qoyod applies local validation of the currency code and the tax currency, so the invoice only reaches the Authority when it is compliant. You issue the invoice, and we take care of the currency’s correctness.

Where do you go after this guide?

Code 1016 is part of a wider system of e-invoicing errors. To understand its position and what is related to it:

• For the comprehensive reference to all invoicing errors: ZATCA e-invoicing errors.
• To understand the family of logical and calculation errors that code 1016 belongs to: business rule validation errors.
• To understand the structure of the invoice header and its fields including the currency fields: Invoice header fields.
• For the complete e-invoicing system from Qoyod: The electronic invoice.

Frequently asked questions

What is the correct currency code for the Saudi riyal in the electronic invoice?

The correct code is SAR in three uppercase Latin letters under the ISO 4217 standard. Any other format such as “SR” or the text symbol ﷼ is rejected by the platform with code 1016. Adopt the standard ISO 4217 code alone in the sent data.

Can I issue an invoice in dollars in electronic invoicing?

Yes in export cases, where the document currency is allowed to be USD or another foreign currency. But the tax currency TaxCurrencyCode must always remain SAR , because the tax return in the Kingdom is filed in Saudi riyals.

Why is my invoice rejected with code 1016 even though the currency is Saudi riyal?

Usually because the code was sent in a non-standard format such as “SR” or in lowercase, or because the tax currency was sent in a currency other than the riyal. Verify that the code is SAR in three uppercase letters, and that TaxCurrencyCode equals SAR exactly.

What is the difference between the document currency and the tax currency?

The document currency DocumentCurrencyCode is the currency of the invoice values — price and total — and it may be foreign in export. The tax currency TaxCurrencyCode is the currency of the VAT amount, and it must be the Saudi riyal in all local invoices without exception.

How do I detect code 1016 locally before sending?

Apply local validation to every invoice before building it: make sure the currency code is from the approved ISO 4217 list, that the tax currency is in Saudi riyals, and that the amounts are consistent with the declared currency. Qoyod applies this validation automatically before sending to the platform.

Does Qoyod support issuing invoices in multiple currencies?

Yes, Qoyod supports multiple currencies in the transactions that call for it, while sending each currency’s code under ISO 4217 and keeping the tax declared in Saudi riyals as the platform requires, so you do not run into code 1016.