E-Invoice Signature Errors: Diagnose and Fix Them

When ZATCA’s system rejects your e-invoice with a vague error message about an “invalid signature” or an “unknown certificate,” the problem is usually not in the invoice data itself. It is in the cryptographic stamp: the digital signature that ties the invoice to the issuer’s identity and proves it has not been altered after issuance. Signature errors are among the most common issues that halt integration in Phase 2 of e-invoicing, and among the hardest to understand because their messages are terse and technical.

This guide focuses on one type of problem only: signature and cryptographic-stamp errors. We will not cover invoice-field errors, VAT, or the tax registration number. We will take each common signature error and show the symptom you see, the root cause behind it, and the practical fix step by step. The goal is for you to leave here able to diagnose the rejection message yourself instead of trying random fixes.

Why do these errors deserve a standalone guide? Because their impact on your business is direct. A tax invoice in business-to-business (B2B) transactions must be cleared by a Fatoora platform before it is handed to the buyer. If its stamp is rejected, you have no valid invoice, and the whole transaction may stall. In business-to-consumer (B2C) invoices, reporting is required within twenty-four hours, and a rejected stamp means a pile-up of unreported invoices and exposure to penalties. Understanding these errors is therefore not a technical luxury but an operational necessity.

If you use a compliant accounting platform such as Qoyod, most of these errors are handled automatically behind the scenes. But understanding how the stamp works remains useful when integrating directly with the technical specification for the cryptographic stamp, when diagnosing a rejection from ZATCA’s system, or when connecting an in-house system to a Fatoora platform.

How the cryptographic stamp works before we talk about its errors

Before diagnosing any error, you need a clear picture of how signing works. A Phase 2 e-invoice is not a signed PDF file. It is an XML file in UBL 2.1 format that is digitally signed using the XAdES standard, with the signature embedded inside a standard extension called UBLExtensions.

The signature is computed as a cryptographic hash of the invoice content, and that hash is then encrypted with the issuer’s private key. The private key is tied to a digital certificate issued by ZATCA called the Cryptographic Stamp Identifier (CSID). The Fatoora platform verifies the signature using the public key that accompanies the certificate. If any element in this chain breaks, the stamp is rejected.

The approved signing algorithm is ECDSA on the elliptic curve secp256k1, with the SHA-256 hash function. These are not optional details. ZATCA enforces these parameters precisely, and any deviation from them produces a signature that the platform rejects even if it is mathematically valid. For a deeper explanation of this mechanism, see the technical specification for the digital signature.

It helps to remember that the signing chain passes through four interconnected stages. It starts with generating the certificate signing request (CSR) with the correct parameters, then registering the certificate with ZATCA and obtaining the Cryptographic Stamp Identifier, then computing the signature over the invoice’s canonical form, and finally embedding the signature and its properties inside the XML file in the required order. Each of the eight errors we will discuss falls into one of these four stages. Once you know which stage you are in, you know where to look for the fix.

Why all this strictness? Because the cryptographic stamp is what turns the invoice from an editable document into a trusted, non-repudiable one. The signature proves the issuer’s identity, guarantees that the invoice content has not changed, and binds it to an irreversible timestamp. These three guarantees are the essence of Phase 2, which is why the platform rejects any signature that fails to satisfy any one of them precisely.

Reading a signature error message correctly

Before going through the errors one by one, learn how to read the rejection response. When a stamp is rejected, ZATCA’s system returns a JSON response containing a list of errors, each with a code, a message, and a category. Here is a simplified sample of a rejection response due to an invalid signature:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "invalid-signature",
        "category": "CRYPTOGRAPHIC_STAMP",
        "message": "The signature value does not match the invoice hash."
      }
    ]
  },
  "clearanceStatus": "NOT_CLEARED"
}

Pay attention to three elements in each message. The code field pinpoints the type of error. The category field tells you the error is in the stamp layer, not in the invoice data. And the clearanceStatus field confirms the invoice was not cleared. Every error we discuss below appears in this form, with only the code code changing.

A map of the eight signature errors

Signature errors fall into three families: errors tied to the certificate and its identity, errors in computing the signature itself, and errors in the signature’s structure inside the XML file. The map above distributes the eight most common errors across these families. We will take them one by one.

Error one: invalid signature (invalid-signature)

Symptom: ZATCA’s system responds with the code invalid-signature and a message stating that the signature value does not match the invoice hash. The invoice is rejected and not cleared.

Root cause: This error means the cryptographic hash that was signed does not equal the hash the platform computes from the invoice content. The most common cause is that the signature was computed over one version of the invoice, then a single character in it was changed after signing, even a single space or a blank line. Any later modification to the XML breaks the match instantly.

Fix: Make sure signing is the last operation performed on the file. Do not reformat the XML, add spaces, or change the character encoding after computing the signature. Compute the hash, sign it, and send the file exactly as is, without any later touch. If you use Qoyod, this process is handled automatically and there is no way to manually interfere with the file after signing.

A practical example of the error: An integration team saves the signed invoice in a database, then re-reads it before sending. During the read, an XML-processing library adds a blank line or automatically reorders the tag attributes. The signature did not change, but the content it protects did, so the match breaks. The solution is to send the signed file itself without reprocessing, or to store it as raw text that no library touches after signing.

Error two: signed over wrong canonical form

Symptom: The same invalid-signature code, but the invoice was not touched after signing, and the signature is still rejected. This is the sneakiest error because everything appears fine.

Root cause: The cryptographic hash is not computed over the XML text as you see it, but over its canonical form after applying the canonicalization algorithm that ZATCA mandates. If you compute the signature over the raw text instead of the canonical form, or use a different canonicalization algorithm, you produce a hash that is mathematically correct but does not match what the platform computes. The result is a rejection even though the signature is “correct” from your point of view.

Fix: Apply the standard canonicalization algorithm specified in the specification to the relevant elements before computing the hash. Make sure canonicalization covers the same elements in the same order the platform expects. This is a precise integration point, and it is the number-one reason manually built integrations fail. Approved systems apply the correct canonical form automatically.

Why a signature fails despite being mathematically valid

The core idea is that the signature must be computed over what the platform sees, not over what you see. Any difference, even a single whitespace, between the two versions breaks the match. This is why the specification distinguishes precisely between the “text” and the “canonical form.”

Error three: expired or unknown CSID certificate

Symptom: A code indicating the certificate is invalid or expired, such as a message about a certificate unknown to the platform or outside its validity period. The invoice is rejected at the identity level, not the signature level.

Root cause: The Cryptographic Stamp Identifier (CSID) is a certificate with a defined validity period. When it expires, every signature produced with its key becomes rejected. Likewise, if the certificate is revoked or was not registered correctly with ZATCA, the platform will not recognize it. Sometimes the issuer sends a signature using a certificate from an environment different from the one the platform expects.

Fix: Check the certificate’s expiry date and renew it before it expires. Make sure the certificate used in signing is the same certificate registered with ZATCA for this establishment and this device. For a deeper understanding of the nature of this certificate and its lifecycle, see the article the CSID certificate and the Cryptographic Stamp Identifier. In Qoyod, this certificate and its renewal are managed automatically as part of the integration with the Fatoora platform.

Error four: mixing up the compliance and production certificates

Symptom: Invoices were passing in the test environment, then suddenly started being rejected in live operation, or vice versa. The error message indicates the certificate is not valid for this operation.

Root cause: There are two distinct certificates in the integration journey. The Compliance CSID is used in the simulation environment to pass compliance tests. The Production CSID is used in the live environment after passing compliance. Signing in the production environment with the compliance certificate, or sending test invoices with the production certificate, produces an immediate rejection because each environment accepts only its own certificate.

Fix: Clearly separate the test and production environments, and make sure each environment uses its correct certificate. After passing the compliance tests, replace the compliance certificate with the production certificate before going live. Qoyod provides a safe simulation environment for testing before moving to live issuance, which prevents this mix-up between the two certificates.

Error five: wrong ECDSA / secp256k1 params

Symptom: An error code indicating an unsupported signing algorithm or invalid key parameters. The signature is rejected at the level of verifying the key structure itself.

Root cause: ZATCA mandates the ECDSA algorithm on the secp256k1 curve specifically. Some software libraries use a different default curve such as secp256r1 or prime256v1, so a technically valid key is generated but on a non-approved curve. Likewise, the hash function may be computed with an algorithm other than SHA-256, so the signature is rejected. The result is a key the platform does not accept even though it is sound in itself.

Fix: Set the cryptography library explicitly to the secp256k1 curve when generating the key, and do not rely on the default. Make sure the hash function is SHA-256. When generating the certificate signing request (CSR), specify these parameters precisely so the certificate is issued on the correct curve from the start. This setup is configured once during integration, and an approved system handles it automatically.

Error six: the signed properties (XAdES) are incomplete

Symptom: An error code indicating that the signed signature properties are incomplete, such as a missing certificate digest or timestamp inside the XAdES structure.

Root cause: The XAdES standard requires embedding a set of Signed Properties inside the signature, most notably the issuing certificate’s digest and the signing time. These properties are part of the signed content, meaning they are included in computing the hash. If one of them is omitted or placed outside the scope of the signature, the system considers the structure incomplete and rejects it.

Fix: Make sure the SignedProperties element contains the certificate digest and the timestamp, and that it is referenced among the elements included in the signature. Verify that every mandatory property is present and in its correct place inside the XAdES structure. This is one of the integration points most prone to manual error, because it requires a precise understanding of the element order.

An important detail: The certificate digest inside the signed properties must be computed over the same certificate used to verify the signature. If it is computed over an old certificate after renewal, or over a certificate from a different environment, the error will appear as a missing property even though the element exists. Always verify that the reference certificate in the properties is the actual certificate used in signing. Also pay attention to the timestamp: it must be in a valid time format consistent with the issuance time, because a mismatch may be interpreted as an invalid property.

Error seven: wrong order of signature elements inside UBLExtensions

Symptom: An error code indicating an invalid extension structure or a signature element in an unexpected position. The invoice is rejected before the mathematical signature is even verified.

Root cause: The cryptographic stamp lives inside a UBLExtensions extension with a specific order of elements. Placing the signature in the wrong position, mixing up the order of the sub-elements, or forgetting one of the standard wrappers makes the system unable to read the signature at all. Here the rejection is structural, not mathematical.

Fix: Follow the element order specified in the technical specification for the cryptographic stamp literally. Do not improvise the order of the sub-elements. Verify that the signature is embedded inside the correct extension and that every standard wrapper is present. Verifying the structure is simpler than diagnosing a mathematical error, but it requires strict adherence to the schema.

A quick checklist before sending the signed invoice

Before sending any signed invoice, go through the checklist above. Six points cover the three families of errors. If they all pass, the likelihood of a rejection due to the signature becomes very small. This list saves hours of random diagnosis.

Error eight: issuer identity mismatch in the certificate

Symptom: A message indicating that the issuer data on the invoice does not match the certificate data, such as a different tax registration number between the invoice and the certificate.

Root cause: The certificate carries the identity of the issuing establishment, and the invoice must match it. If an establishment’s invoice is signed with another establishment’s certificate, or the tax registration number differs between the two fields, the system rejects the invoice because the declared identity does not equal the cryptographically proven identity. This is a common error when managing several establishments on one system.

Fix: Make sure the certificate used in signing belongs to the same establishment that issues the invoice. When managing several establishments, tie each establishment to its own certificate and do not mix them. Check that the tax registration number matches between the invoice data and the certificate data before sending.

How Qoyod helps you avoid signature errors from the start

Most of the eight errors above arise from manual integration with a Fatoora platform, where the developer personally handles generating the certificate, computing the canonical form, and building the XAdES structure. Qoyod eliminates these risks by managing the entire cryptographic-stamp layer on your behalf.

Qoyod manages the Cryptographic Stamp Identifier (CSID) and its renewal automatically, so you never deal with an expired or unregistered certificate. It generates the XML file in UBL 2.1 format and signs it with the correct algorithm and parameters (ECDSA on secp256k1 with SHA-256) without any manual setup. It also builds a complete XAdES structure with its signed properties and places the signature in its correct position inside the standard extension.

Before moving to live operation, Qoyod provides a safe simulation environment where you test compliance without the risk of rejection in production, which prevents mixing up the compliance and production certificates. And at live issuance, it connects the invoice to the Fatoora platform in real time for clearance (B2B) or for reporting within twenty-four hours (B2C), fully compliant with the Phase 2 requirements of the Zakat, Tax and Customs Authority.

Reference table: the eight errors at a glance

This table gathers the eight errors with each error’s code, family, and short fix, so you can return to it quickly when facing a rejection. Read the error code from ZATCA’s response and look it up in the first column.

Note that half the errors go back to the certificate and its identity, not to the mathematical signature. This is an important lesson: many integration teams focus their effort on the signing algorithm while the real problem is in managing the certificate, its validity, and its environment. Always start your diagnosis from the certificate before diving into the computation.

Why this recurs in manual integration specifically

The common factor across most of these errors is that they appear in integrations an in-house team builds directly with a Fatoora platform. The reason is that the developer personally handles a long chain of precise decisions: which elliptic curve, which canonicalization algorithm, which XAdES properties are mandatory, and which order for the elements. A single mistake in any decision produces a rejected signature, and the returned message does not always point precisely to the wrong decision.

It gets harder because some errors only appear when moving to production. The integration passes in the simulation environment, then is rejected in the live environment due to a different certificate or a different setting between the two environments. This is why a safe test environment, whose behavior matches production, is a decisive element in avoiding surprises. In it, you test every case before it costs you in reality.

When using an approved accounting system, these precise decisions move off your team’s shoulders and onto a system tested with thousands of establishments. You do not choose a curve, configure a canonicalization algorithm, or order XAdES elements manually. You write the invoice, and the system handles the entire stamp layer. This is the practical difference between an integration that consumes weeks of diagnosis and one that works from day one.

A three-step method to diagnose any signature error

If you face an error code we did not cover here, follow the same method. First, read the category field in the rejection response. If it is CRYPTOGRAPHIC_STAMP, the problem is in the signature, not in the invoice data. This saves you from searching in the wrong place.

Second, identify the family. Is the error in the certificate (validity, environment, identity)? Or in the computation (the curve, the canonical form, the match)? Or in the structure (element order, XAdES completeness)? Each family has a different fix entry point, and identifying it cuts half the road.

Third, isolate the last change. If invoices were passing then stopped, what changed? A certificate renewal, a move to production, a cryptography-library update, a change in XML generation. The error is usually in the last change. These three steps turn a vague rejection message into a specific, fixable diagnosis.

A final practical tip: keep a log of every rejection you face, containing the error code, its time, and the change that preceded it. Over time this log reveals a clear pattern, so you learn that most of your rejections, for example, come after renewing the certificate, or when moving between environments. This awareness of the pattern is more valuable than memorizing error codes, because it treats the cause, not the symptom. And the less you intervene manually in the stamp layer, the lower the likelihood of an error in the first place.

Signature errors look complex because they are technical and terse, but they are in fact confined to eight known cases. Once you understand how the stamp works and the families of errors, diagnosing any rejection becomes a matter of minutes. And if you want to avoid this layer entirely, a compliant accounting platform that handles the stamp on your behalf is the shortest route to invoices cleared on the first attempt. For more on integration errors in general, see the guide ZATCA errors in e-invoicing, and for the full picture of e-invoicing, start from the e-invoicing page e-invoicing from Qoyod.