Translations

Translate fiscalization error codes and messages to English. Supports static lookup for known error codes and AI-powered translation as a fallback for unrecognized errors.

All endpoints require authentication.

Translate an error

POST /v1/translations/errors

Translates a country-specific fiscalization error into English with classification metadata.

Request body

Field	Type	Required	Description
error_code	string	Yes	The error code from the tax authority (e.g., 1105 for AEAT)
error_message	string	No	The original error message (improves AI translation quality)
country	string	Yes	Country code: ES, IT, or FR
system	string	No	Fiscalization system (e.g., ticketbai, verifactu, sii, sdi)

Example

curl -X POST https://api.zyntem.dev/v1/translations/errors \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zyn_test_abc123def456..." \
  -d '{
    "error_code": "1105",
    "country": "ES",
    "system": "verifactu"
  }'

Response 200 OK

{
  "error_code": "1105",
  "country": "ES",
  "system": "verifactu",
  "original_message": "El NIF del obligado tributario no está identificado en la AEAT",
  "translation": "The taxpayer NIF is not registered with AEAT",
  "category": "validation",
  "severity": "error",
  "retriable": false,
  "user_message": "The tax ID provided is not recognized by the Spanish tax authority. Please verify the NIF is correct.",
  "source": "static"
}

Response fields

Field	Type	Description
error_code	string	Echoed from request
country	string	Country code
system	string	Fiscalization system (if provided)
original_message	string	Original error message in the source language
translation	string	English translation of the error
category	string	Error classification (see below)
severity	string	error, warning, or info
retriable	boolean	Whether retrying the operation may succeed
user_message	string	Non-technical message suitable for end users
source	string	static (known error code) or ai (AI-translated)

Error categories

Category	Description
validation	Input data validation failure
auth	Authentication or authorization issue
submission	Error during submission to tax authority
network	Network or connectivity issue
configuration	System configuration problem
unknown	Unrecognized error type

Translation sources

Static lookup -- For known error codes, Zyntem returns pre-translated messages from its built-in error catalog. Currently supported:

Country	System	Coverage
Spain (ES)	TicketBAI, Verifactu, SII	AEAT error codes
Italy (IT)	SDI	SDI notification error codes

Static translations include curated category, severity, retriable, and user_message values.

AI fallback -- When an error code is not in the static catalog, Zyntem uses Claude to translate the error message, classify it, and generate a user-friendly explanation. AI translations are cached permanently to avoid redundant calls.

Errors

Status	Error	Cause
400	error_code is required	Missing error code
400	country is required	Missing country code