ZATCA Fatoora API Error Handling: A Field Guide to Clearance Failures

The invoice was signed, the XML validated, the queue job dispatched, and ZATCA said no. Zatca fatoora api error handling is the part of Phase 2 integration that separates a demo from a production system, because clearance failures happen at the worst possible moments: during peak billing, during ZATCA maintenance windows, and at 2 AM when nobody is watching. I have debugged these failures in live Laravel systems, and they fall into a small set of patterns you can engineer against once you know them.

Quick Answer: Handle ZATCA clearance failures with a layered strategy: validate payloads locally before submission to catch schema errors early, retry transient failures (rate limits, timeouts, gateway errors) with exponential backoff in a queue, route permanent rejections to a dead-letter queue with human alerting, and run a nightly reconciliation job comparing your invoice states against ZATCA records. Never let a failed clearance fail silently.

The Failure Taxonomy: What Actually Goes Wrong

Every clearance failure I have seen belongs to one of four buckets. Categorizing correctly matters because each bucket gets a different response:

The expensive mistake is retrying a schema rejection five times and then paging someone at midnight for what is actually a code bug. Your error handler must read the response category before deciding. Zatca clearance vs reporting matters here too: a failed clearance blocks invoice issuance and needs loud alerting, while a failed report means the invoice already went out and needs quiet reconciliation.The Retry Architecture

Transient failures get the queue treatment. This job wraps the submission from my integration guide with classified retries:

<?php

namespace App\Jobs;

use App\Models\Invoice;
use App\Services\ZatcaSigningService;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Log;

class SubmitZatcaInvoiceWithRetry implements ShouldQueue
{
    use Queueable;

    public int $tries = 6;

    public function __construct(public Invoice $invoice) {}

    public function backoff(): array
    {
        // 2m, 8m, 30m, 2h, 8h: respects ZATCA rate limits and
        // gives transient outages time to clear.
        return [120, 480, 1800, 7200, 28800];
    }

    public function handle(ZatcaSigningService $signer): void
    {
        $result = $signer->attemptClearance($this->invoice);

        if ($result->isValidationError()) {
            // Permanent: retrying is pointless. Park it for a human.
            $this->invoice->zatcaPayload()->create([
                'status' => 'rejected',
                'error_code' => $result->errorCode,
                'error_detail' => $result->errorDetail,
            ]);
            Log::error('ZATCA validation rejection', [
                'invoice_id' => $this->invoice->id,
                'code' => $result->errorCode,
            ]);
            return; // do not rethrow: no retry for bad payloads
        }

        if ($result->isTransientError()) {
            // Throw to trigger the backoff retry cycle above.
            throw new \RuntimeException(
                "Transient ZATCA failure: {$result->errorCode}"
            );
        }

        $this->invoice->update([
            'zatca_status' => 'cleared',
            'zatca_cleared_at' => now(),
        ]);
    }

    public function failed(\Throwable $e): void
    {
        // All retries exhausted: dead-letter with a loud alert.
        $this->invoice->update(['zatca_status' => 'needs_attention']);
        Log::critical('ZATCA clearance exhausted retries', [
            'invoice_id' => $this->invoice->id,
            'error' => $e->getMessage(),
        ]);
        // Notify::route('slack', ...)->notify(new ZatcaClearanceFailed($this->invoice));
    }
}

The failed() hook is the most important method in the file. A fatoora retry queue without a dead-letter destination is just a slower way to lose invoices.

The Nightly Reconciliation Job

Queues handle the known failures. Reconciliation catches the unknown ones: the job that died with the worker, the webhook that never arrived, the invoice stuck in submitted for three days. One scheduled command, every night:

<?php

namespace App\Console\Commands;

use App\Models\Invoice;
use App\Services\ZatcaSigningService;
use Illuminate\Console\Command;

class ReconcileZatcaInvoices extends Command
{
    protected $signature = 'zatca:reconcile';
    protected $description = 'Reconcile local invoice states with ZATCA';

    public function handle(ZatcaSigningService $signer): int
    {
        // Anything submitted but not cleared for over 2 hours is suspect.
        $stuck = Invoice::where('zatca_status', 'submitted')
            ->where('zatca_submitted_at', '<', now()->subHours(2))
            ->get();

        foreach ($stuck as $invoice) {
            $status = $signer->queryInvoiceStatus($invoice);

            match ($status) {
                'cleared' => $invoice->update(['zatca_status' => 'cleared']),
                'rejected' => $invoice->update(['zatca_status' => 'needs_attention']),
                default => SubmitZatcaInvoiceWithRetry::dispatch($invoice),
            };
        }

        $this->info("Reconciled {$stuck->count()} invoices.");

        return self::SUCCESS;
    }
}

Run it on the scheduler nightly. It is boring, unglamorous, and it is the reason your finance team trusts the system.ZATCA Sandbox vs Production Behavior

One more trap: the zatca sandbox production gap. The sandbox accepts payloads that simulation rejects, and simulation accepts timing patterns that production punishes under load. Always do your final validation pass in simulation, and after going live, watch the first week of production clearances like a hawk. Log every rejection code with the full payload hash so patterns surface fast.

Should I retry a ZATCA validation rejection?

No. A validation rejection means your payload is wrong: bad XML, bad signature, duplicate counter. Retrying the same bytes will fail the same way. Log it, alert a developer, fix the payload generator, then resubmit manually.

How do I handle ZATCA maintenance windows?

Pause the submission queue during announced windows and let invoices accumulate in pending state, then drain the queue when the window closes. Never let jobs burn their retry budget against a known outage.

What is the dead-letter queue pattern here?

Invoices that exhaust all retries move to a needs_attention state with the full error context attached, plus an alert to your team channel. A human investigates, fixes the root cause, and re-dispatches. Nothing disappears silently.

Clearance vs reporting: which failures are worse?

Failed clearance blocks the invoice from being issued, so it is operationally urgent but contained. Failed reporting means the invoice already went to the customer, so the business impact is compliance risk rather than a blocked sale. Both need the same retry machinery; only the alerting urgency differs.

Summary & Production Takeaways

Zatca fatoora api error handling is a classification problem first and a retry problem second. Sort every failure into validation, transient, auth, or maintenance; retry only the transient ones with backoff; park validation failures for humans; and back everything with a nightly reconciliation job. Build this before your first production invoice, not after your first 2 AM page. For the full integration walkthrough, read my ZATCA Phase 2 Laravel integration guide, or talk to a senior software engineer in Riyadh about getting your compliance pipeline production-ready.