Errors · Unify | Complyance docs

What each error from Unify means and what to do about it, and the shape of a validation error.

Validation errors

422 means the document failed validation. errors lists every problem, so fix them all before you send the document again.

Validation failure — HTTP 422json

{
  "documentId": "01K5EXAMPLE00000000000142",
  "documentNumber": "INV-2026-000184",
  "message": "Your invoice could not be validated. Review the errors and try again.",
  "validationStage": "gets",
  "errors": [
    {
      "code": "IBR-015",
      "getsPath": "totals.amountDue",
      "payloadPath": "totals.amountDue",
      "message": "An Invoice MUST have the Amount due for payment (ibt-115).",
      "severity": "error",
      "ruleSet": "ae:tax_invoice"
    }
  ]
}

Field	Type	Description
`code`	string or null	The rule identifier when the check comes from a published rule, such as `IBR-015` or a Saudi `BR-KSA-*` rule.
`getsPath`	string or null	The field in GETS.
`payloadPath`	string or null	The field in the payload you sent.
`message`	string	What is wrong.
`severity`	string or null	For example `error`.
`ruleSet`	string or null	The rules the document was checked against, as `country:documentType`.

validationStage is gets when a field or rule failed. Fix the fields in errors, then send the document again with the same documentNumber: Complyance updates the document it stored as Needs Correction and keeps its documentId. See Retries and duplicates.

When validationStage is xml, producing the e-invoice failed after the fields passed, and errors is empty. The message reads Something went wrong. Please contact support. Email support@complyance.io with the documentId and the time of the request.

These errors are the ones people meet most:

GETS-HEAD-010: a document with this documentNumber is already stored, and the message names its status. If you were retrying a request that timed out, the first request worked: find the document by searching for its number. If this is a new document, give it a number you have not used before.

AE-PEPPOL-008: the seller’s Peppol ID is not one your workspace has onboarded in this environment. In the UAE, set parties.seller.peppolId to your company’s 10-digit TIN, with the scheme 0235, exactly as it was registered when you onboarded the company.

The rules behind these errors differ by country, and each country lists its own: United Arab Emirates, Saudi Arabia, Malaysia, Oman, Belgium and Germany.

Other errors

Any other status means the request was refused before the document was checked. After any 4xx status in this table nothing was stored, so send the request again once you have fixed the cause.

Status	Meaning	What to do
`400`	The request is malformed, names an unsupported country, has no `purpose`, has no `source`, or its `source` is not in `name:version` form.	Fix the request. Do not retry it unchanged.
`401`	The API key is missing, invalid, revoked or expired.	Check the `Authorization` header and the key. See Authentication.
`403`	The key belongs to a different environment from `environment` (`permission_denied`), or it is read-only (`insufficient_permission`).	Use a sandbox key with `sandbox` and a production key with `production`, with write permission.
`404`	The `source` is not in your workspace.	Check the source’s name and version, character for character.
`409`	More than one source in your workspace has this name and version.	Archive or rename the duplicate source, then send again.
`412`	The source’s mapping cannot take invoices yet. The body’s `reason` says why; see below.	Fix the mapping, then send again.
`413`	An XML body is larger than 8 MiB.	Split it into smaller batches.
`415`	An XML request has the wrong `Content-Type`, or a compressed body.	Send `Content-Type: application/xml` with an uncompressed UTF-8 body.
`429`	Too many requests in a short time.	Wait for the number of seconds in `Retry-After`, then send again.
`500`	Something went wrong on our side.	Send again after a short wait, then with longer waits. If it keeps failing, email support@complyance.io with the time of the request.
`503`	A service the request needs is briefly unavailable.	Send again after a short wait, then with longer waits.

Most refusals have a body with error:

Unknown source — HTTP 404json

{
  "error": "No source matches the requested name and version"
}

A request that fails the body checks returns code and message:

Malformed request — HTTP 400json

{
  "code": "invalid_argument",
  "message": "Invalid request."
}

When the mapping is not ready

A 412 has code set to failed_precondition, a message and a reason:

No mapping — HTTP 412json

{
  "code": "failed_precondition",
  "message": "No integration mapping matches the requested source, country, and document type",
  "reason": "mapping_not_found"
}

`reason`	What it means	What to do
`mapping_not_found`	No mapping covers this source, country and document type.	Create a mapping for the source, or add the country and document type to its mapping.
`mapping_ambiguous`	More than one mapping covers them.	Keep one mapping for the source, country and document type.
`mapping_inactive`	The mapping is switched off.	Make the mapping active again in the Integration engine.
`required_scenarios_incomplete` or `required_scenarios_empty`	The test cases the mapping needs have not all passed. The message lists the ones still open.	Run them in Test your mapping, then send again.
`uat_scope_locked`	Production is not open yet for this country, document type and request format.	Send a matching invoice in sandbox until it is accepted as compliant, then send the production invoice again.

With uat_scope_locked, details names the countryCode, documentType and request format that are still locked. JSON and XML requests open separately.

Try these errors in the API playground.