Error Codes

Reference for all validation and API error codes.

API Errors

Authentication

Error	HTTP Status	Description
missing_api_key	401	No API key provided
invalid_api_key	401	API key is invalid or revoked
key_disabled	403	API key has been disabled

Rate Limiting

Error	HTTP Status	Description
rate_limited	429	Too many requests
quota_exceeded	403	Monthly quota exceeded

Request Errors

Error	HTTP Status	Description
validation_failed	400	Input validation failed
invalid_json	400	Request body is not valid JSON
not_zugferd	400	PDF is not ZUGFeRD/Factur-X

Validation Errors

Input Validation

These errors occur when required fields are missing or invalid:

Code	Path	Message
REQUIRED	$.invoice.number	Invoice number is required
REQUIRED	$.invoice.date	Invoice date is required
REQUIRED	$.invoice.seller	Seller information is required
REQUIRED	$.invoice.seller.name	Seller name is required
REQUIRED	$.invoice.seller.vatId	Seller VAT ID is required
REQUIRED	$.invoice.buyer	Buyer information is required
REQUIRED	$.invoice.buyer.name	Buyer name is required
REQUIRED	$.invoice.items	At least one item is required
INVALID	$.invoice.date	Invalid date format (use YYYY-MM-DD)
INVALID	$.invoice.items[n].unit	Invalid unit code

EN 16931 Business Rules

Code	Rule	Description
BR-01	Invoice number	Invoice shall have a specification identifier
BR-02	Seller	Invoice shall have a seller
BR-03	Buyer	Invoice shall have a buyer
BR-04	Seller name	Seller shall have a trading name or name
BR-05	Seller address	Seller shall have an address
BR-06	Seller country	Seller address shall have a country code
BR-07	Buyer name	Buyer shall have a name
BR-08	Buyer address	Buyer shall have an address
BR-09	Issue date	Invoice shall have an issue date
BR-10	Currency	Invoice shall have a currency code
BR-11	Due date	Payment due date shall be valid
BR-12	Line item	Invoice shall have at least one line
BR-13	Line ID	Each line shall have an identifier
BR-16	Calculation	Sum of line amounts shall equal total

Code List Validation

Code	Rule	Description
BR-CL-01	Invoice type	Invoice type code shall be valid
BR-CL-10	Currency	Currency code shall be from ISO 4217
BR-CL-23	Unit	Unit code shall be from UN/ECE Rec 20
BR-CO-09	VAT format	VAT identifier format must match country
BR-CO-10	Buyer VAT	Buyer VAT identifier if applicable

Example Error Response

{
  "error": "validation_failed",
  "message": "Invoice validation failed",
  "details": [
    {
      "path": "$.invoice.seller.vatId",
      "code": "REQUIRED",
      "message": "Seller VAT ID is required"
    },
    {
      "path": "$.invoice.items[0].unit",
      "code": "BR-CL-23",
      "message": "Unit code 'HOUR' is not valid. Use 'HUR' instead."
    }
  ]
}

Handling Errors

TypeScript

const result = await client.invoice()
  .number('2026-001')
  .generate()

if (!result.success) {
  for (const error of result.errors) {
    switch (error.code) {
      case 'REQUIRED':
        console.log(`Missing field: ${error.path}`)
        break
      case 'BR-CL-23':
        console.log(`Invalid unit code at ${error.path}`)
        break
      default:
        console.log(`${error.code}: ${error.message}`)
    }
  }
}

Python

result = client.invoice().number("2026-001").generate()

if not result.success:
    for error in result.errors:
        if error.code == "REQUIRED":
            print(f"Missing field: {error.path}")
        elif error.code == "BR-CL-23":
            print(f"Invalid unit code at {error.path}")
        else:
            print(f"{error.code}: {error.message}")