Responses and Errors

Evaluate two result layers

Every caller must evaluate:

  1. the HTTP result; and
  2. the business result in the response body.

A 2xx status means that the HTTP operation reached the service successfully. It does not guarantee that AECloud validation, storage, LHDN submission, or final document validation succeeded.

Submission response content

Submission responses are assembled from processing steps. Depending on timing and outcome, the body can contain:

  • response_step01 — AECloud payload validation;
  • response_step02 — record storage plus sale identifiers;
  • response_step03 — immediate or later processing decision;
  • later steps for document generation, LHDN authentication, submission, polling, and result storage;
  • sale_id and sale_guid;
  • document_no and preferred-submission information;
  • LHDN_submission_uid, LHDN_accepted_uuid, and LHDN_longId, when available;
  • LHDN_Submission_Status or Document_Status; and
  • overall_status.

Field presence varies. Write a tolerant parser that ignores unknown fields, accepts absent not-yet-applicable fields, and preserves the original response for controlled troubleshooting.

Business result words

The current service uses several result vocabularies:

  • SUCCESS for accepted processing or state change;
  • FAILED for a failed processing step;
  • ERROR for validation, lookup, or runtime errors; and
  • FAILURE for operations such as a denied or unsuccessful cancellation.

Check case-insensitively and do not treat only one of these words as failure.

Common initial validation errors

The request can fail because:

  • the JSON is invalid;
  • a required top-level object is missing;
  • a required property is null or empty;
  • a numeric field contains non-numeric text;
  • preferred_submission_on is not now, setting, or conso;
  • the merchant is inactive, unsubscribed, expired, or unknown;
  • the outlet entitlement is exhausted;
  • qr_custom_guid is duplicated across different documents;
  • a matching record is already valid, in progress, or locked; or
  • the original invoice for an adjustment cannot be resolved.

Authentication and transport errors

Handle these separately from document errors:

  • DNS, TLS, connection, and timeout failure;
  • malformed token request;
  • invalid or expired client credentials;
  • expired bearer token;
  • request too large;
  • unsupported content type;
  • rate limiting; and
  • server-side 5xx errors.

Capture HTTP status, response headers, response body, endpoint, duration, and a safe internal correlation ID. Never log bearer tokens, client secrets, full TIN/identification values, or complete document payloads in general application logs.

Invalid LHDN document

An Invalid status is not a transient network error. Preserve the document number, accepted or rejected identifiers, status, and validation detail available through AECloud. Correct the source or configuration only after understanding the error, then follow the approved correction or resubmission process.

MyInvois distinguishes synchronous submission acceptance from later full validation. See the official Submit Documents and Get Document Details documentation for the external processing model.