Handling 502/504 Timeouts and Duplicate Invoices in Phase 2

Clearance and Reporting
1

Hello ZATCA Developer Community,

We are integrating our system with ZATCA Phase 2 e‑Invoicing API for more than 50 customers.

Sometimes, when submitting invoices, we get 502 / 504 timeout errors. The issue is that if we retry the submission after a timeout, we sometimes get a duplicate invoice error, which suggests that the invoice may have already been processed even though our system did not receive the response.

We would like guidance on:

  1. How to check if an invoice has already been received and processed by ZATCA after a timeout.

  2. If there is an official API to get the last status or response of a submitted invoice.

  3. The recommended procedure for safely resubmitting invoices to avoid duplicates.

Since we manage e‑invoicing for 50+ customers, it’s critical for us to handle timeouts and retries correctly. Any tips, examples, or references from official documentation would be very helpful.

Thank you!
CC: @Ankit.K.Tiwari @idaoud

2

Hi,

  1. You can refer for on this thread for the duplicate invoices response. Duplicate Invoices
  2. As far as I know, there is no Official API for this, @Ankit.K.Tiwari , please confirm
  3. For timeouts, It is ok to resubmit it since it didn’t reach the ZATCA server, and apply the validations for handling Duplicates or already exist Invoices.

I hope this answer atleast gave you some clarification.

1 Like