Troubleshooting

Token request fails

Check that the request uses the environment's token URL, form encoding, grant_type=client_credentials, and the current merchant client ID and secret. Confirm that a credential was not regenerated after deployment.

Do not print the full token request or secret while debugging.

Version works but submission fails

GET /version/ tests access only. Check merchant status, subscription dates, outlet entitlement, LHDN configuration, company code, and document payload.

The response says the JSON is invalid

Validate the exact transmitted bytes with a JSON parser. Common causes are:

  • trailing commas;
  • unescaped quotation marks or control characters;
  • a byte-order mark;
  • sending form data instead of raw JSON;
  • wrapping the payload inside body_text; or
  • serializing the JSON object twice into a quoted string.

A required object or field is missing

Compare the request with the Payload reference. Property names are case-sensitive. Remember the newer required routing fields shiftCode and qr_custom_guid, and the required sales fields lhdnSubmission and saleType.

Document date conversion fails

Send a UTC timestamp with milliseconds and Z, for example:

2026-08-26T02:30:00.000Z

Do not send only 2026-08-26 to the current submission contract.

Merchant or subscription error

Confirm that aec.companyCode is the merchant GUID for the same environment, the merchant is active and subscribed, and the subscription end date has not passed.

Outlet limit exceeded

The requested outlet name was not found and the active-outlet count reached the subscribed limit. Check for spelling or spacing variants before requesting a subscription change. Manage the correct outlet in the Merchant Console, then retry with the exact name.

Duplicate QR GUID

aec.qr_custom_guid already belongs to a different document. If retrying the same document, preserve all original business keys. If it is genuinely new, generate a new cryptographically strong GUID and correct the source record.

Upload denied as valid, in progress, or locked

Do not retry the submission. Retrieve status by GUID or submission range. Use the appropriate adjustment, void, or cancellation workflow based on the current state.

Adjustment cannot resolve the original invoice

Check that originalInvoiceDocumentNo exactly matches an invoice stored for the same merchant and relevant outlet, and that the normal/self-billed families are not mixed.

Status lookup returns no record

  • Ensure sale_guid is sent as a header.
  • Use the document family's matching status endpoint.
  • For range lookup, send company_guid, submission_from, and submission_to as headers using YYYY-MM-DD.
  • Remove outlet_name temporarily to test whether the outlet spelling is the mismatch.
  • Process all pages of a collection response.

Business body reports failure with HTTP success

This is expected for some handled business errors. Parse overall_status, response_step messages, response, or response_msg as applicable. Do not classify the request from the HTTP status alone.

Cancellation fails

Confirm that the document is individually submitted, has an accepted UUID, is in a cancellable state, is within the permitted cancellation period, has no active referencing document that blocks cancellation, and includes a meaningful reason.

Escalating to support

Email support@einvoicecloud.com with:

  • environment name, but not credentials;
  • endpoint and HTTP method;
  • safe correlation ID;
  • source document number and AECloud sale GUID;
  • request and response timestamps with time zone;
  • HTTP status and sanitized response;
  • last known document status; and
  • steps already taken.

Never email the client secret, bearer token, full unredacted payload, or full personal identifiers.