ZATCA API 429: Too Many Requests / Rate Limit Exceeded

📌 Overview & Impact

ZATCA Fatoora clearance & compliance endpoints enforce throttling limits. Rapid concurrent requests trigger HTTP 429 rate limit errors.

⚠️ Common Causes for Rejection

• ✕ Sending clearance API requests synchronously in a tight loop during batch invoice generation
• ✕ Bursts of POS checkout traffic without rate limiting queue or retry backoff
• ✕ Multiple concurrent threads using the same EGS CSID credentials simultaneously
• ✕ Aggressive automated retry without respecting Retry-After header

✅ How to Fix & Resolve

💻 Code Comparison: Invalid vs Compliant UBL 2.1 XML

// Anti-pattern: Synchronous loop firing 100 requests in parallel
await Promise.all(invoices.map(inv => zatcaApi.post('/invoices/clearance', inv)));

// Best practice: Rate-limited queue with exponential backoff
const queue = new PQueue({ concurrency: 3, interval: 1000, intervalCap: 5 });
for (const invoice of invoices) {
  await queue.add(() => sendWithRetry(invoice));
}

❓ Frequently Asked Questions

🔗 Related ZATCA Rules