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

SDK Error Codes

The SDK and Direct API share the same error codes. When you use the SDK, error responses from pushToUnify will contain the same errorCode values documented here. See the SDK Guides for language-specific error handling patterns.

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.