Error Handling Guide

Consejo

Última actualización el 2026-04-20.

The attached guide provides an overview of common errors when sending records via SIGN IT lite and how to resolve them. It addresses errors returned by the POST /records endpoint (record submission), including both HTTP-level issues and application-level failures.

How to identify the error?

Check the logs field in the API response. Example:

{
  "state": "FAILED",
  "logs": [
    {
      "severity": "ERROR",
      "message": "Authentication error: ADE portal has not responded successfully"
    }
  ]
}

The error message prefix (e.g. Authentication error, Validation error, Submission error, etc.) determines the error category.

Category	Meaning	Retry?
Safe to retry*	The receipt was not submitted to AdE as the error occurred before the receipt reached the AdE submission endpoint.	Yes, with a new idempotency key
Requires verification	The receipt may have been submitted to AdE as the error occurred during or after the receipt submission attempt to AdE.	Verify on the AdE portal first. If the receipt does not appear, retry with a new idempotency key
If you encounter an unknown or HTTP 500 error, please email dev-support@fiskaly.com and include sufficient details so we can investigate and advise on the next steps.

HTTP 503 error is returned in case of a transient infrastructure unavailability. It is always safe to retry with a new idempotency key. If this error persist beyond 1–2 minutes, the infrastructure may be experiencing extended pressure. Log the transaction in your emergency register and contact dev-support@fiskaly.com if the issue does not resolve.

*Compliance note: Fiscal transactions are expected to be reported in real time. Delays or retries may introduce compliance risks and may not meet regulatory requirements. 

fiskaly provides technical tooling but does not guarantee compliance, which remains the customer’s responsibility. Any retry or recovery process should follow legally permitted timeframes and local regulations. Please refer to the guide for further details. Note: Some error prefixes — specifically Entity validation error and fiscalization invalid — can also occur during taxpayer commissioning. In that context, the remediation is simpler: update the Taxpayer data based on the error message and retry the commissioning.