Clearance Errors in the E-Invoice: A Practical Fix Guide

You have built your integration with the Fatoora platform, and you send your first tax invoice to the Clearance path. You wait for the authority’s response to learn whether the invoice was accepted and stamped, or rejected. On the clearance path for business invoices (B2B), the invoice is not handed to the buyer until the Zakat, Tax and Customs Authority (ZATCA) digitally stamps it. Any error here therefore stops the invoice entirely, it does not merely delay it. This page is a practical guide to clearance-path errors specifically, within Qoyod’s e-invoicing system.

The essential distinction that must be clear before anything else: the clearance path differs from the reporting path. A full tax invoice addressed to another business (B2B) goes through clearance, meaning it is sent to the authority before being handed to the buyer, and awaits an immediate digital stamp. A simplified invoice addressed to a consumer (B2C), on the other hand, is handed over immediately and then reported within 24 hours. Clearance errors have a different nature from reporting errors, because the invoice here is genuinely on hold until the response arrives. This page covers the clearance side only, while the reporting-errors guide covers the other side, and both fall under the parent reference in the Zakat, Tax and Customs Authority errors guide.

The target audience here is the developer or technical integration lead who builds or maintains the connection between an accounting system and the Fatoora platform through the Clearance API. You will therefore find real JSON examples of the authority’s responses, along with an explanation of the technical fields as they actually appear. English technical codes such as clearanceStatus and clearedInvoice are kept as-is, because they are the actual field names in the API.

How the clearance path works, and why its errors differ

On the clearance path, your system sends the signed invoice to the endpoint dedicated to clearance on the Fatoora platform. The authority verifies the invoice immediately and returns a response carrying the clearance status in the clearanceStatus field, along with a stamped copy of the invoice in the clearedInvoice field if it succeeds. This stamp is what makes the invoice legal and deliverable. Without it, you have no right to send it to the buyer.

To understand the diagnostic logic, remember that the invoice passes through successive validation layers and stops at the first layer that fails. The order helps you know where to look first before you waste time in the wrong place.

• Structure and XML format layer. Is the document syntactically sound? Does it follow the UBL 2.1 schema? Are the mandatory fields present and in their proper places?
• Business rules layer. Are the values logical? Does the sum of the line items equal the total? Does the calculated VAT match the amount?
• Signature, hash and stamp layer. Is the digital signature valid? Is the operational certificate (CSID) valid? Does the hash value of the previous invoice match?
• The clearance layer itself. Did the invoice reach the correct clearance endpoint? Did the response come back in the expected time with a valid clearanceStatus?

Reading the clearance response

The decisive field in every response is clearanceStatus. The value CLEARED means the invoice was accepted and stamped, and you will find its stamped copy in clearedInvoice. The value NOT_CLEARED means rejection, and you will not find a stamped invoice. Alongside it comes the validationResults list, which details the error and warning messages. This structure is fixed, and understanding it cuts diagnosis time in half.

The stamped invoice in clearedInvoice usually comes Base64-encoded, containing the complete signed XML document together with the authority’s stamp. This particular copy, not the one you sent, is the legal document you must hand to the buyer and keep in your archive. Decoding it reveals the signature and stamp elements the authority added, which are what distinguish an accepted invoice from the draft you created before sending. Rely on this copy for display, archiving and printing, not on what your system generated locally.

1. Invoice rejected at clearance (NOT_CLEARED)

This is the most common and most important error on the clearance path. The invoice reaches the authority, fails to pass the validation rules, and the authority returns the clearance status NOT_CLEARED with a list of rejection reasons. The invoice here is not legal, and it must never be handed to the buyer.

Symptom. The response carries clearanceStatus with the value NOT_CLEARED, the clearedInvoice field is empty or absent, and the errorMessages list is full of messages explaining the rule that was broken. The HTTP status code is often 303 or 400 depending on the type of failure.

The following example is an actual response for an invoice rejected at clearance because the calculated tax amount did not match the 15% rate:

{
  "clearanceStatus": "NOT_CLEARED",
  "clearedInvoice": null,
  "validationResults": {
    "status": "ERROR",
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-KSA-EN16931-09",
        "category": "EN_16931",
        "message": "The VAT category tax amount does not equal the taxable amount multiplied by the VAT rate."
      }
    ]
  }
}

Solution. Do not resend before you fix the cause. Read the code field in each message, as it pinpoints the broken rule precisely. In the example above, recalculate the tax amount for each line item so that it equals the taxable value multiplied by the rate, then re-sign the invoice and send it. After every change to line items or amounts you need a new signature, because the old signature no longer matches the content. In Qoyod, the tax is calculated and the invoice is reconstructed automatically according to the authority’s rules, so this class of errors does not reach clearance at all in most cases.

Common examples of clearance rejection messages

• Invalid tax registration number. The seller’s or buyer’s tax number does not follow the authority’s format of 15 digits beginning and ending with the digit 3.
• Invoice total does not balance. The sum of the line items plus tax does not equal the total amount declared in the invoice.
• Missing mandatory field. Absence of the seller’s address, the issue date, or the currency identifier in the position the specification requires.
• Wrong invoice type for the path. Sending a simplified invoice (B2C) to the clearance endpoint instead of the reporting path.

The six clearance errors and how to handle them

2. Invoice accepted with a warning (CLEARED with warningMessages)

Not every message from the authority is a rejection. Sometimes the authority returns the invoice with a clearance status of CLEARED, meaning accepted and stamped, but attaches a warningMessages list with non-blocking notes. The invoice here is legal and deliverable, and the warning does not stop it.

Symptom. clearanceStatus with the value CLEARED, and the clearedInvoice field carries the actually stamped invoice, but the warningMessages list is not empty. The common mistake here is for the system to treat the warning like a rejection, halting a valid invoice for no reason.

{
  "clearanceStatus": "CLEARED",
  "clearedInvoice": "PHN1Ymxxxx...base64-signed-xml...",
  "validationResults": {
    "status": "WARNING",
    "errorMessages": [],
    "warningMessages": [
      {
        "type": "WARNING",
        "code": "BR-KSA-EN16931-08",
        "category": "EN_16931",
        "message": "Buyer address is recommended but missing"
      }
    ]
  }
}

Solution. Hand the invoice to the buyer as usual, since it is stamped and legal. The distinguishing rule your system must build is clear: delivery depends on clearanceStatus, not on the presence of messages in the list. If the status is CLEARED, the invoice is delivered even if it carries warnings. Log the warnings in an internal record and address them later to improve your data quality, such as adding the buyer’s missing address, but do not let them block delivery.

3. Signature or hash rejection during clearance

Before the invoice reaches the business-rules check, the authority verifies the integrity of its digital signature, its cryptographic stamp, and the hash chain. If this layer fails, the invoice is rejected at clearance with the status NOT_CLEARED and messages pointing to the signature, the certificate, or the hash value. This class is troublesome because it can appear suddenly on a system that was working, for example when the operational certificate CSID expires.

Symptom. The response is NOT_CLEARED, and the error messages mention invalid signature, invalid certificate, hash mismatch, or previous invoice hash. The invoice is neither stamped nor delivered.

{
  "clearanceStatus": "NOT_CLEARED",
  "clearedInvoice": null,
  "validationResults": {
    "status": "ERROR",
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "signing-error",
        "category": "SIGNATURE",
        "message": "Invoice signature is invalid or certificate (CSID) has expired."
      }
    ]
  }
}

Solution. Start by checking the validity of the operational certificate CSID and its expiry date. The operational certificate (Compliance Cryptographic Stamp Identifier) is the cryptographic identity with which you stamp your invoices, and it has a validity period that must be renewed before it expires. If the certificate is valid, verify that the hash value of the previous invoice in the hash chain matches what the authority expects, because any gap in the sequence breaks the chain. Note also that the signature must be computed on the final content of the invoice, so any change after signing invalidates it. In Qoyod, the CSID certificate is managed, its cycle renewed, and the hash chain built automatically, so this class of errors practically disappears.

4. Timeout with no response from clearance

Clearance is an instant operation, but it depends on a network connection to the Fatoora platform. Sometimes you send the invoice and no response comes back within the set timeout, either because of a temporary slowdown in the authority’s service or a connection outage on your side. This case is dangerous because it is ambiguous: you do not know whether the invoice arrived and was actually stamped, or did not arrive at all.

Symptom. The clearance request does not return a complete response body; instead it ends in a timeout or network error, or comes back with a 5xx-class status code indicating a temporary service fault.

Solution. Do not assume failure and do not resend immediately with a new invoice number, because you may create a duplicate if the first invoice was actually stamped. The correct rule is to query the invoice’s status by its identifier first before retrying. If it turns out it was not stamped, resend with an exponential backoff policy: try after a few seconds, then after a minute, with a maximum number of attempts. This behavior protects your invoice sequence from duplication and handles temporary faults gracefully. In Qoyod, retry and status checking are managed automatically, so the user is never left in this ambiguity.

5. Delivering the invoice before clearance is complete

This is a procedural error, not a technical one, but it is among the most serious on the clearance path. The rule is explicit: a business (B2B) invoice is not handed to the buyer before the authority stamps it. Handing over an unstamped copy means handing over an illegal document, exposes the business to a violation, and confuses the buyer who will later receive a different stamped copy.

Symptom. The system generates the invoice and sends it to the buyer the moment it is created, without waiting for the CLEARED status from clearance. The problem is usually discovered when the buyer complains that the copy differs, or during a review that finds no digital stamp on the delivered invoice.

Solution. Make the delivery step conditional on the clearance status, not on invoice creation. The correct sequence: create the invoice, sign it, send it to clearance, wait for clearanceStatus with the value CLEARED, take the stamped invoice from clearedInvoice, then hand it to the buyer. Do not deliver anything before the stamp. The difference between this path and the reporting path is essential here: in reporting, the simplified invoice is delivered immediately and then reported, whereas in clearance the stamp always precedes delivery. Qoyod enforces this sequence automatically, so an invoice cannot be delivered before it is stamped.

The correct sequence for the clearance path

6. Wrong or contradictory Clearance-Status

The Fatoora platform returns, in the response header, a header named Clearance-Status that summarizes the clearance result, alongside the clearanceStatus field inside the response body. Confusion sometimes arises when the system reads one source and ignores the other, or when it interprets an unexpected value in this header as success. The result is a wrong decision about the invoice: delivering what was not stamped, or withholding what was stamped.

Symptom. An apparent contradiction between what you read from the Clearance-Status header and what the response body carries, or a value in the header that the system does not handle explicitly, so it falls into a wrong default behavior.

Solution. Make the final decision based on the clearanceStatus field inside the response body, and treat the Clearance-Status header as a quick indicator only. Handle the two known values CLEARED and NOT_CLEARED explicitly, and treat any other unexpected value as a failure that requires stopping and querying, not as an implicit success. This principle protects you from the most serious of errors: delivering an invoice based on a wrong interpretation of a status that was not actually stamped.

The most frequent rejection codes at clearance

The code field in every error message is the diagnostic key. The text of the message may change in wording, but the code is fixed and refers to a specific rule. Below are the most prominent codes that business invoices run into at clearance, their practical meaning, and the action required for each.

• A code related to the tax number. The tax registration number of the seller or buyer does not match the approved format. Make sure it is 15 digits beginning and ending with the digit 3, and that the buyer’s number is mandatory on a business invoice.
• A code related to the tax calculation. The VAT amount for a line item or for the invoice does not equal the taxable value multiplied by the rate. Recalculate each line item separately before aggregating.
• A code related to totals balancing. The sum of the line items plus tax does not match the declared total. Review the rounding in each line item, as small differences accumulate and break the balance.
• A code related to a missing mandatory field. Absence of an element the specification requires, such as the issue date, the currency identifier, or the seller’s address. Add the field in its correct position within the UBL structure.
• A code related to the signature or certificate. An invalid signature or an expired CSID certificate. Renew the certificate and make sure the signature is computed on the final content.
• A code related to the hash chain. The hash value of the previous invoice does not match what the authority expects. Check the invoice sequence and that there is no gap or duplication in the chain.

Handling the code, not the message alone, keeps your system’s logic stable no matter how the message wording changes. Log the full code in your error record, as it is what you need when contacting the authority’s technical support or when tracking a recurring pattern in your invoices.

Test in the sandbox before production

Most sudden clearance errors in production could have been caught early in the sandbox environment the Fatoora platform provides. Moving straight to production without sufficient testing turns every error into a broken invoice in front of a real customer. So build your integration line in two clear stages.

In the sandbox, send samples that represent your real cases: an invoice at the standard tax rate, another exempt, another zero-rated, and an invoice with a currency and multiple line items. Verify that each one comes back with the status CLEARED, and inspect the stamped invoice in clearedInvoice. Also deliberately try failure cases, such as a wrong tax number, to make sure your system reads NOT_CLEARED and behaves correctly. This exercise reveals gaps in the logic that distinguishes an error from a warning before it costs you a real invoice.

Once the results are stable in the sandbox, move to production with the actual operational certificate CSID. Remember that the sandbox and production environments use different certificates and endpoints, so do not mix them up. A common mistake is for the system to remain pointed at the sandbox endpoint after the move, so invoices appear accepted while they were not actually registered in production.

A step-by-step methodology for diagnosing clearance errors

When a clearance error reaches you, do not start by guessing. Follow a fixed sequence that leads you to the cause in the least time.

• Read clearanceStatus first. CLEARED means success even with warnings. NOT_CLEARED means a rejection that requires a fix. Treat any other value as a failure and stop.
• Separate the error from the warning. errorMessages block the invoice, and warningMessages do not block it. Do not mix them up in your system’s logic.
• Read the code field, not just the message. The code pinpoints the broken rule precisely, and the message is a human explanation that may change.
• Identify the layer. Is the error in the signature and certificate, in the business rules, or in the path itself? Each layer has a different solution.
• Fix, then re-sign. Any change to the invoice content voids the previous signature and requires a new signature before resending.

The difference between clearance errors and reporting errors

Many errors attributed to clearance are in reality a mix-up between the two paths. The full tax invoice (B2B) goes through clearance and awaits an immediate stamp before delivery. The simplified invoice (B2C) is delivered immediately to the consumer and then reported within 24 hours. Sending an invoice via the wrong path produces an immediate rejection. Always verify the invoice type before choosing the endpoint: the clearance endpoint for business invoices, and the reporting endpoint for simplified invoices. This distinction alone prevents a wide slice of errors before they occur.

If the error in front of you concerns simplified invoices that are reported after delivery, its reference is the separate reporting-errors guide, not this page. As for the fundamentals shared between the two paths, such as the response structure and the difference between an error and a warning, you will find them in the parent authority errors guide, and the details of the endpoint and the connection mechanism in the Clearance API page, while the clearance guide explains the concept from its roots.

How Qoyod helps you get past clearance errors

The bulk of clearance errors never reach the user at all when using an approved accounting system. Qoyod is a fully integrated Saudi accounting system, officially approved by the Zakat, Tax and Customs Authority, that builds a specification-compliant XML invoice, signs it, manages the CSID operational certificate and its renewal, builds the hash chain, sends the invoice to clearance, and waits for the stamp before allowing delivery. With this, signature errors, business-rule errors, and premature-delivery errors practically disappear.

Qoyod also handles timeout and retry cases safely, querying the invoice’s status before resending to prevent duplication, and clearly distinguishing between the warning that does not block delivery and the rejection that halts it. The result is that the integration lead focuses on their work instead of chasing error codes.

Most importantly, Qoyod stores the stamped copy from clearedInvoice and links it to the invoice in your account, so there is no confusion between the draft that was sent and the legal document that was stamped. On any rejection, the system displays the reason for rejection in understandable wording instead of leaving the user facing a raw English code, and guides them to the appropriate fix. This combination of full compliance with the authority’s specification and intelligent handling of responses is what makes the clearance path in Qoyod run smoothly in the vast majority of cases, even at high daily invoice volumes.

If you are building your integration yourself or maintaining an existing system, the principles on this page apply to any clearance path whatever your system is. But if your goal is to issue compliant tax invoices without carrying the burden of managing certificates, the hash chain and retry logic yourself, then relying on an approved system saves you this entire road.

Frequently asked questions

What is the difference between CLEARED and NOT_CLEARED? CLEARED means the authority accepted the invoice and stamped it, and you find its stamped copy in the clearedInvoice field, so you are entitled to hand it to the buyer. NOT_CLEARED means rejection, there is no stamped invoice, and you must fix the cause and re-sign and resend.

Should I deliver the invoice if it comes back CLEARED with warnings? Yes. Warnings in warningMessages do not block delivery. As long as the status is CLEARED and the invoice is stamped in clearedInvoice, deliver it and log the warning to address it later.

What do I do if the clearance response does not come back within the timeout? Do not resend immediately. Query the invoice’s status by its identifier first, as it may have actually been stamped. If it was not stamped, retry with an exponential backoff policy and a maximum number of attempts to avoid duplication.

Why is my signature suddenly rejected after it was working? The most common cause is the expiry of the CSID operational certificate. Check its date and renew it, then make sure the hash chain is intact and that the signature is computed on the final content of the invoice.

May I deliver the invoice to the buyer before clearance? No. A business (B2B) invoice is not delivered before the authority’s stamp. Early delivery means an illegal document. Always make the delivery step conditional on the CLEARED status.

Where do I read the final clearance status? Rely on the clearanceStatus field inside the response body as the decision source, and treat the Clearance-Status header as a quick indicator only. Treat any value other than CLEARED or NOT_CLEARED as a failure that requires querying.