API submission errors

Use this guide if your team submits e-invoices to JomeInvoice through the API. For validation errors that appear inside the app, see Why your invoice was rejected.

Authentication

The API token is expired or invalid

Error message: Authentication failed: the API token is expired or invalid

What it means: The access token used for the request is no longer valid.

Steps to fix:

1. Request a new access token.
2. Retry the request with the new token.

The client credentials are invalid

Error message: Invalid client credentials or OAuth client not found

What it means: The client ID or client secret is wrong.

Steps to fix:

1. Confirm the client ID and secret. Both are in Settings → Workspace Settings → Organisation, on your Main HQ under the Client Secret tab - see Organisation, Main HQ and branches. If you have mislaid either one, reveal or copy it there; you do not need to regenerate to get it back.
2. Only if a credential has been exposed, use Regenerate on that tab, then update your integration with the new values. The old pair stops working straight away, so submissions keep failing until the integration is updated.

Required headers are missing

Error message: Authorization header is required or X-Account-Id header is required

What it means: A required header was not sent.

Steps to fix:

1. Include the Authorization header with your access token.
2. Include the X-Account-Id header for the account you are submitting for.

Request payload

A required field is missing

Error message: Messages such as Missing required field: Id, Missing required field: IssueDate, Missing required field: DocumentCurrencyCode, Missing required field: InvoiceLine, or Missing required field: LegalMonetaryTotal.

What it means: The submitted e-invoice is missing a field the format requires.

Steps to fix:

1. Include the invoice number, issue date, currency, supplier and buyer details, at least one line item, and the totals.
2. Resubmit the corrected payload.

The issue date format is wrong

Error message: Invalid IssueDate format

What it means: The date is not in the expected YYYY-MM-DD format.

Steps to fix:

1. Format the issue date as YYYY-MM-DD.
2. Resubmit.

A credit, debit, or refund note is missing its reference

Error message: BillingReference is required for invoice type ...

What it means: A credit, debit, or refund note must reference the original invoice it adjusts.

Steps to fix:

1. Add the original invoice reference (BillingReference) for note types.
2. Resubmit.

The batch is too large

Error message: Batch size N exceeds the maximum of 500 invoices per request

What it means: A single request contains more than 500 invoices.

Steps to fix:

1. Split the submission into batches of 500 invoices or fewer.
2. Send each batch separately.

Service responses

The upstream service is unavailable

Error message: Upstream API unavailable (often returned as a 502).

What it means: A service the API depends on was briefly unreachable. This is usually temporary.

Steps to fix:

1. Retry the request after a short wait.
2. Contact JomeInvoice support if it persists.

Related articles

• Why your invoice was rejected
• Bulk upload invoices