Retries and Idempotency

Retries must preserve the identity of the original business document. A timeout does not prove that AECloud rejected the request.

Stable keys

Generate and store these before the first POST:

• sales.documentNo;
• aec.qr_custom_guid;
• company code;
• outlet name;
• terminal name; and
• shift code.

Do not create a new document number or QR GUID simply because the HTTP response was lost.

AECloud matches an existing normal invoice using company, outlet, terminal, and document number. Before the record becomes valid, in progress, or locked, a later upload can update the stored record and increment its upload attempt. A valid, in-progress, or locked record denies re-upload. The QR GUID also has a uniqueness constraint.

Ambiguous-result procedure

When a submission times out or the connection closes before the response is received:

1. do not immediately generate new identifiers;
2. query the matching status-by-submission endpoint for the company, date range, and outlet;
3. match the returned saleCode or documentNo to the source record;
4. if found, store its saleGuid and continue reconciliation;
5. if not found after a reasonable propagation interval, retry once with the original payload and identifiers; and
6. alert for manual review if the result remains ambiguous.

Retry categories

Category	Retry approach
Authentication failure	Refresh the token once; stop if credentials remain invalid.
Connection or timeout before a known result	Reconcile first, then retry with the same identity if absent.
Rate limit	Honor Retry-After and apply exponential backoff with jitter.
Temporary 5xx	Retry a bounded number of times with backoff, preserving document identity.
Initial payload validation error	Do not retry unchanged. Correct the source data.
Invalid LHDN status	Do not retry unchanged. Investigate the validation result.
Valid, in-progress, locked, voided, or cancelled record	Do not resubmit as a retry. Follow the appropriate business process.

Polling discipline

Use one reconciliation worker rather than having every POS terminal poll independently. Start with an interval of at least several seconds and increase it for long-running or scheduled documents. Stop active polling at a terminal status.

The official MyInvois integration practices describe rate limiting and Retry-After behavior. AECloud may apply additional environment controls, so follow the limits supplied during onboarding.