ZATCA Phase 2 Rejection Errors: A Troubleshooting Guide for SMEs
Master ZATCA Phase 2 compliance. Learn how to identify and fix common e-invoicing rejection errors, from PIH mismatches to XML validation issues.
Introduction to ZATCA Phase 2 Rejection Errors
Transitioning to ZATCA Phase 2 (Integration Phase) represents a significant technological leap for Saudi SMEs. Unlike Phase 1, where invoices were simply generated and stored, Phase 2 requires real-time or near-real-time integration with the FATOORA portal.
This integration brings a new challenge: Rejection Errors. When your ERP or accounting software submits an invoice to the ZATCA API, it undergoes rigorous validation. If the invoice fails, it is rejected, potentially leading to compliance gaps, delayed payments, and even fines.
In this guide, we will break down the most common ZATCA rejection errors, why they happen, and how to fix them using best practices and Qeemah’s automated ZATCA solutions. If you’re still onboarding, start with our comprehensive Fatoora Saudi portal guide first.
Understanding the Validation Process: Clearance vs. Reporting
Before diving into errors, it is vital to understand the two workflows in Phase 2:
- Clearance (B2B Invoices): Standard tax invoices must be sent to ZATCA in real-time. ZATCA validates the XML and returns it with a cryptographic stamp. If it is rejected, the invoice is not legally issued.
- Reporting (B2C Invoices): Simplified tax invoices are issued to the customer first and must be reported to ZATCA within 24 hours. Rejection here means your reporting obligation has not been met.
💡 Tip: Use our ZATCA Readiness Checker to see if your current system is prepared for these workflows.
Common ZATCA Error Categories
ZATCA rejection errors typically fall into four categories:
1. Cryptographic & Security Errors
These occur when the connection between your system and ZATCA is compromised or misconfigured.
- Invalid CSID: Your Cryptographic Stamp Identifier is expired or revoked.
- Signature Mismatch: The digital signature applied to the XML does not match the content.
2. Sequence & Continuity Errors (The ‘Chain’)
ZATCA Phase 2 requires each invoice to be linked to the previous one to prevent tampering.
- ICV (Invoice Counter Value): An incremental number. If you skip a number or reuse one, ZATCA rejects it.
- PIH (Previous Invoice Hash): Every invoice must contain the SHA-256 hash of the previous invoice’s XML.
3. Business Rule Violations (BR-KSA)
These are the most common errors. They relate to Saudi-specific tax laws and VAT logic.
- VAT Category Mismatch: Using the wrong code (e.g., ‘S’ for Standard, ‘Z’ for Zero Rated) for a specific tax rate.
- Calculation Errors: The sum of line items does not equal the total VAT or the total amount including VAT.
4. Schema & XML Structure Errors
If the XML file does not follow the UBL 2.1 standard required by ZATCA, the API will reject it immediately.
Top 10 ZATCA Rejection Error Codes and How to Fix Them
| Error Code | Meaning | Solution |
|---|---|---|
| KSA-REJECT-01 | Invalid XML Structure | Ensure your software generates UBL 2.1 XML. Use a ZATCA XML Viewer to debug. |
| KSA-9 | Previous Invoice Hash Mismatch | The PIH in the current invoice does not match the hash of the last successfully submitted invoice. Re-sync your sequence. |
| BR-KSA-31 | VAT Category Error | Verify that the VAT rate (e.g., 15%) matches the Category Code (e.g., ‘S’). |
| BR-KSA-01 | Invalid QR Code | The TLV-encoded QR code is missing mandatory fields like the Digital Signature or Hash. |
| KSA-3 | Duplicate Invoice | You are trying to submit an Invoice Number (IRN) that already exists in the ZATCA database. |
| KSA-25 | Invalid UUID | The Universal Unique Identifier is missing or not in the correct RFC 4122 format. |
| BR-KSA-09 | Total Amount Mismatch | The TaxInclusiveAmount must equal TaxExclusiveAmount + TaxAmount. Check for rounding errors. |
| KSA-7 | Invalid Issue Date | The invoice date is in the future or too far in the past (beyond the 24-hour reporting window for B2C). |
| BR-KSA-26 | Missing Buyer Information | For B2B invoices over a certain threshold, the Buyer’s VAT number or address is mandatory. |
| 401 Unauthorized | Authentication Failed | Your Binary Security Token (BST) has expired. You must renew your CSID via the Fatoora portal. |
Step-by-Step: How to Resolve a Rejected Invoice
Step 1: Analyze the Response Payload
When ZATCA rejects an invoice, the API returns a JSON response containing an errors array. Look for the code and message fields.
Step 2: Check the XML against XSD
Validate your XML against the ZATCA-provided XSD (XML Schema Definition). Most errors are due to missing tags or incorrect data types (e.g., putting text in a numeric field).
Step 3: Verify the Hash Chain
If you receive a KSA-9 error, your local database is out of sync with ZATCA. You must retrieve the hash of the last accepted invoice and use it as the PIH for your new submission.
Step 4: Correct VAT Calculations
Saudi VAT law is strict about rounding. Ensure your VAT calculations follow the ‘round half up’ rule at the line-item level and the total level as specified in the ZATCA technical guidelines.
How to Prevent Rejections Before They Happen
✅ Use a ZATCA-Qualified Provider: Don’t build from scratch. Use a platform like Qeemah that is already integrated and tested with the ZATCA Sandbox and Production environments.
✅ Implement Pre-Validation: Your software should run a “mock validation” before calling the ZATCA API. This catches 90% of schema and calculation errors locally.
✅ Automate CSID Renewal: Set up alerts to renew your security certificates before they expire to avoid 401 Unauthorized errors.
✅ Maintain a Robust Sequence Log: Keep a strict digital log of ICVs and PIHs. If a submission fails due to a network error, your system must know whether to retry the same sequence or move to the next.
How Qeemah Helps You Stay Compliant
Handling ZATCA Phase 2 manually is nearly impossible for SMEs. Qeemah simplifies the entire process:
- Automatic Integration: We handle the complex API handshake, digital signatures, and UUID generation.
- Real-time Validation: Our system checks your invoice against ZATCA’s business rules before submission, reducing rejection rates to near zero.
- Chain Management: Qeemah automatically manages your PIH and ICV sequences, ensuring no breaks in your digital record.
- ZATCA Dashboard: Monitor the status of every invoice (Cleared, Reported, or Rejected) from a single accounting dashboard.
Don’t let ZATCA errors slow down your business.
Explore Qeemah’s ZATCA Phase 2 Features | View Pricing Plans