Error Codes Reference

Platform Error Codes

Code	Meaning	Action
`AUTH_INVALID_API_KEY`	API key is invalid or doesn't match the environment	Check your key and that `env` matches
`AUTHORIZATION_ERROR`	You are not authorised to perform this action	Verify your key has the right permissions
`VALIDATION_ERROR`	One or more request fields failed validation	Check the `errors` array for details
`REQ_INVALID_INPUT`	A specific field has an invalid or missing value	Check the `path` in the error object
`LOGICAL_TYPE_UNSUPPORTED`	`logicalDocumentType` is not valid for the country	Use a supported document type for your country
`COUNTRY_RULE_NOT_SUPPORTED`	The country is not supported for the requested operation	Verify the country code is in the supported list
`VALIDATION_FAILED`	Invoice payload failed country-specific rules	Review your invoice data against country requirements
`SUBMISSION_FAILED`	Invoice was valid but the government submission failed	Retry or contact support with the `requestId`
`BULK_ABORTED`	Bulk request was stopped due to an error (`continueOnError: false`)	Fix the failing invoice and resubmit
`DOCUMENT_NOT_FOUND`	Document lookup failed for given `documentId` and authenticated client	Verify `documentId` belongs to your workspace/client
`NOT_FOUND`	The requested document was not found	Verify the `uuid` and `documentId` are correct
`INTERNAL_ERROR`	Unexpected server error	Retry with exponential backoff; contact support if it persists

Validation Engine Codes (Invoice-Level, Country-Specific)

In addition to the generic platform codes above, Unify can return country validation-engine codes in:

data.results[].errors[]
data.results[].validation.errors[]
errors[] (for top-level validation failures)

These are actual invoice/business-rule codes from documents-service validators.

Code Example	Category	Meaning (Typical)
`SYS.VALIDATOR_FAILURE`	Validation system	Validator failed unexpectedly
`GETS-GEN-001`	GETS general	Schema validation failed
`GETS-HEAD-010`	GETS header	Duplicate document number
`AE-MANDATORY-001`	UAE mandatory	Missing invoice number
`KSA-DOC-001`	KSA document	KSA duplicate document number
`MY-DOC-001`	Malaysia document	Malaysia duplicate document number
`MY-TOTAL-001`	Malaysia totals	Invoice total mismatch
`AE-CALC-001`	UAE calculation	Invalid total calculation
`DE-PAYMENT-002`	Germany payment	Invalid IBAN
`BE-PAYMENT-002`	Belgium payment	Invalid IBAN

Understanding Error Responses

Error Response Structure

{
  "status":    "error",
  "code":      "VALIDATION_ERROR",
  "message":   "Request validation failed",
  "requestId": "01J...",
  "timestamp": "2026-02-26T10:00:00.000Z",
  "data":      null,
  "errors": [
    {
      "code":    "REQ_INVALID_INPUT",
      "message": "documentId is required for list action",
      "path":    ["filters", "documentId"]
    }
  ]
}

Troubleshooting Steps

Check the code — Tells you the error category
Read the message — Explains what went wrong
Check the path — Points to the problematic field in your request
Review requestId — Provide this when contacting support

Common Scenarios

API Key Issues

Error: AUTH_INVALID_API_KEY
Fix: Verify your API key is correct and matches the environment (sandbox vs production)

Missing Required Fields

Error: REQ_INVALID_INPUT with path pointing to a required field
Fix: Add the missing field to your request

Unsupported Country

Error: COUNTRY_RULE_NOT_SUPPORTED
Fix: Use a supported country code: SA, MY, BE, AE, SG, DE

Validation Failed

Error: VALIDATION_FAILED with country-specific error code in results[].validation.errors[]
Fix: Review your invoice data against country-specific requirements

Bulk Request with continueOnError: false

Error: BULK_ABORTED when one invoice fails
Fix: Set "continueOnError": true to process remaining invoices, or fix the failing invoice and resubmit

Source of Truth in Codebase

For the complete list of error codes and their definitions, see:

services/documents_service/src/validation/constants/error-codes.ts
services/documents_service/src/services/validation/validation.service.ts

Notes

Exact code depends on country, validator, and failing field/business rule.
Treat code format prefixes (GETS-, MY-, AE-, DE-, BE-, KSA-, SYS.) as stable classification.
Use message + path together with code for actionable UI messages.