# Errors

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.

```json title="Validation failure — HTTP 422"
{
  "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](https://docs.complyance.io/api-reference/unify/submit-and-retrieve/#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](https://docs.complyance.io/one-platform/invoice-portal/documents/search-and-filters/#search-by-document-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](https://docs.complyance.io/countries/ae/onboarding/).

The rules behind these errors differ by country, and each country lists its own: [United Arab Emirates](https://docs.complyance.io/countries/ae/validation-rules/), [Saudi Arabia](https://docs.complyance.io/countries/sa/validation-rules/), [Malaysia](https://docs.complyance.io/countries/my/validation-rules/), [Oman](https://docs.complyance.io/countries/om/validation-rules/), [Belgium](https://docs.complyance.io/countries/be/validation-rules/) and [Germany](https://docs.complyance.io/countries/de/validation-rules/).

## 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](https://docs.complyance.io/api-reference/authentication/#authentication-failures). |
| `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`:

```json title="Unknown source — HTTP 404"
{
  "error": "No source matches the requested name and version"
}
```

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

```json title="Malformed request — HTTP 400"
{
  "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`:

```json title="No mapping — HTTP 412"
{
  "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](https://docs.complyance.io/one-platform/developer-portal/integration-engine/create/) 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](https://docs.complyance.io/one-platform/developer-portal/integration-engine/test/), 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](https://docs.complyance.io/api/?operation=submitDocument).

Source: https://docs.complyance.io/api-reference/unify/errors/