Unify V2 Responses and Errors

Unify V2 uses HTTP statuses to distinguish successful processing, document validation failures, and request or processing errors.

Your client should branch on the HTTP status first and then inspect the response body.

Successful document: HTTP 200

A successfully processed mapping or invoicing request returns a direct document result:

{
  "documentId": "6a7eab425227e2981a38f486",
  "message": "Your invoice was validated and is ready for submission.",
  "Base64XML": "PEludm9pY2U+PC9JbnZvaWNlPg=="
}

Validation failure: HTTP 422

If source mapping succeeds but the converted GETS document or generated XML fails validation, the response contains structured findings:

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

code, getsPath, payloadPath, severity, and ruleSet may be null when the validator cannot provide that information. documentId, validationStage, Base64XML, and debug are optional. Build your client to tolerate missing or null fields.

A 422 is a document validation outcome, not a transport failure. Correct the source data or mapping as appropriate before sending the document again.

Invalid request: HTTP 400

Malformed JSON or a body that does not match the new request schema returns:

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

Other direct request checks can use the same code and message shape.

Check that:

• a single request has country, environment, purpose, source, documentType, and payload at the request root;
• a bulk request has invoices at the root and every item contains those document fields;
• the request does not mix root document fields with the bulk invoices format;
• purpose is mapping for the Integration Engine or invoicing for sending invoices;
• environment is sandbox or production for every document;
• documentType.modifiers is present for every document, even when it is []; and
• the body contains valid JSON.

Authentication and processing errors

Errors raised during authentication, source resolution, or processing can use a smaller shape:

{
  "error": "Source AES:1 was not found"
}

Clients should support both error and message when displaying a non-validation failure.

HTTP status reference

Recommended client handling

1. Check the HTTP status before parsing outcome details.
2. On 200, store documentId and decode Base64XML if your workflow needs the generated XML.
3. On 422, retain the full errors array and show actionable messages without assuming optional fields exist.
4. On other failures, read error or message and retain the response for troubleshooting.
5. Do not make workflow decisions by comparing human-readable message text.
6. Retain documentId and debug.requestId, when present, for support.

Example handling logic:

const response = await fetch(url, requestOptions);
const body = await response.json();

if (response.status === 200) {
  saveDocumentId(body.documentId);
} else if (response.status === 422) {
  showValidationFindings(body.errors ?? []);
} else {
  showRequestError(body.error ?? body.message ?? 'Request failed');
}

Troubleshooting

My request was routed to Unify V1

Confirm that new-api: true is present as an HTTP header on the exact POST /api/v3/unify request. It must not be in the JSON body. An invoices array can be used by both contracts; the header selects the contract, while Unify V2 bulk items use self-contained document fields without defaults.

I received HTTP 403

Confirm that the API key belongs to the correct workspace and environment. Sandbox/mock keys cannot be used for production requests, and production keys cannot be used for sandbox requests.

I received HTTP 404

Verify the complete source alias, including its version. Confirm that the mapping supports your workspace, country, and document type.

I received HTTP 422

Start with payloadPath to locate the source value. Use getsPath, code, and ruleSet to understand the canonical rule. If the source value is correct but the mapped GETS field is not, contact the team responsible for your source mapping.

Unify V1 error responses

Unify V1 uses a different bulk response and error model. If your request uses the defaults and invoices envelope, see the Unify V1 Error Codes instead.

Related documentation

• Unify V2 (Recommended)
• Examples
• Migrate from Unify V1