Comprehensive developer reference for diagnosing and fixing ZATCA Fatoora Portal clearance and compliance rejection codes, complete with XPath contexts and UBL 2.1 XML diffs.
BR-KSA-03 • BR-KSA-03: المعرف الفريد العالمي غير صالح (UUID / KSA-1)
The invoice must contain a valid UUID (KSA-1) conforming to RFC 4122 standard (letters, digits, dashes).
BR-KSA-04 • BR-KSA-04: تاريخ إصدار الفاتورة لا يمكن أن يكون في المستقبل
The document issue date (BT-2) must be less than or equal to the current server date (KSA timezone AST / UTC+3).
BR-KSA-05 • BR-KSA-05: رمز نوع الفاتورة غير صالح (BT-3)
Invoice type code must be one of the agreed UN/CEFACT 1001 codes: 388 (Tax Invoice), 381 (Credit Note), 383 (Debit Note), or 386 (Prepayment).
BR-KSA-06 • BR-KSA-06: كود المعاملة الفرعية للفاتورة غير صحيح (NNPNESB / KSA-2)
The invoice transaction code (KSA-2) must exist in @name attribute of InvoiceTypeCode and respect the 7-digit NNPNESB structure.
BR-KSA-08 • BR-KSA-08: مخطط هوية البائع غير صالح (BT-29)
Seller identification must exist once with an authorized schemeID: CRN (Commercial Registration), MOM, MLS, 700, SAG, or OTH.
BR-KSA-09 • BR-KSA-09: نقص في الحقول الإلزامية للعنوان الوطني للبائع
Seller address must contain all 6 Saudi National Address elements: Street Name, Building Number, Postal Code, City, District, and Country Code ('SA').
BR-KSA-15 • BR-KSA-15: تاريخ التوريد إلزامي في الفواتير الضريبية القياسية
Standard tax invoices (BT-3=388 & KSA-2 starts with 01) must contain the supply date (KSA-5) in Delivery block.
BR-KSA-26 • BR-KSA-26: خطأ في احتساب هاش الفاتورة السابقة (PIH / KSA-13)
Previous invoice hash (KSA-13) must be Base64-encoded SHA-256 digest of the canonicalized previous invoice XML (or the standard zero seed for the 1st invoice).
BR-KSA-27 • BR-KSA-27: رمز الاستجابة السريعة (QR Code / KSA-14) مفقود أو غير مطابق
The document must contain a Base64-encoded TLV QR Code (KSA-14) formatted according to ZATCA Phase 2 security specifications.
BR-KSA-31 • BR-KSA-31: نوع معاملة غير مسموح به في الفاتورة المبسطة
For simplified tax invoices (KSA-2 starting with 02), only third party (pos 3), nominal supply (pos 4), and summary transactions (pos 6) are allowed. Exports & self-billing are forbidden.
BR-KSA-37 • BR-KSA-37: رقم مبنى البائع يجب أن يتكون من 4 أرقام بالضبط
The seller address building number (KSA-17) must contain exactly 4 numeric digits matching the Saudi National Address.
BR-KSA-40 • BR-KSA-40: الرقم الضريبي للبائع يجب أن يتكون من 15 رقماً يبدأ وينتهي بـ 3
Seller VAT registration number (BT-31) must contain exactly 15 digits, where the 1st digit is '3' and the 15th digit is '3'.
BR-KSA-51 • BR-KSA-51: عدم تطابق إجمالي مبلغ البند شامل الضريبة (KSA-12)
The line amount with VAT (KSA-12) must strictly equal Invoice line net amount (BT-131) + Line VAT amount (KSA-11).
BR-KSA-56 • BR-KSA-56: مرجع الفاتورة الأصلية إلزامي للإشعارات الدائنة والمدينة
For credit notes (code 381) and debit notes (code 383), the original invoice billing reference ID (BT-25) is mandatory.
BR-KSA-63 • BR-KSA-63: العنوان الوطني للمشتري إلزامي عندما تكون الدولة السعودية (SA)
If buyer country code is 'SA' on a Standard Tax Invoice, street name, building number, postal code (5 digits), city, district, and country code are all mandatory.
BR-KSA-68 • BR-KSA-68: رمز العملة الضريبية إلزامي ويجب أن يكون 'SAR'
Tax currency code (BT-6) must exist in every invoice and be explicitly set to 'SAR' (Saudi Riyal) under EN16931 rules.
BR-KSA-70 • BR-KSA-70: تنسيق وقت إصدار الفاتورة غير صحيح (KSA-25)
The invoice must contain Issue Time (KSA-25) in either 'hh:mm:ss' (AST local time) or 'hh:mm:ssZ' (UTC format).
BR-KSA-DEC-01 • BR-KSA-DEC-01: نسبة الخصم يجب ألا تتجاوز خانتين عشريتين وبدون رمز %
Allowance and discount percentage values (BT-94, BT-138) must be numeric from 0.00 to 100.00 with max 2 decimals. The '%' symbol is forbidden.
ZATCA-API-429 • خطأ 429: تجاوز الحد الأقصى لمعدل الطلبات في بوابة زاتكا
ZATCA Fatoora clearance & compliance endpoints enforce throttling limits. Rapid concurrent requests trigger HTTP 429 rate limit errors.
INVALID-INVOICE-HASH • خطأ هاش الفاتورة غير صالح: عدم تطابق بصمة الفاتورة الرقمية
The generated SHA-256 digest of the canonicalized invoice does not match the hash verified by ZATCA validator.
Try adjusting your search query or filter by category above.
Qeemah automates BR-KSA validation, ECDSA cryptography, C14N canonicalization, and instant clearance out of the box with zero manual integration pain.