Passa al contenuto principale

Errors and status codes

Internal Validation​

Internal validation errors occur when the data sent in a request does not conform to the expected format or schema defined by the API. For instance, if a field expects a specific type of value, such as a particular enumeration (e.g., "1" for Herr, "2" for Frau, "3" for Divers) or a required structure, any discrepancy from this will trigger a validation error.

External Validation​

In case the external validation via ERiC/ELSTER fails, the error message can be retrieved via the endpoint Download ERiC/ELSTER transmission XML. Note that the XML may contain several errors.

Important: The XML is the raw response sent by ERiC/ELSTER. The fiskaly SIGN DE x Submission API does not interpret the response.

Status 2xx​

Status codes in the 200-299 range indicate success.

Status 4xx​

Status codes in the 400-499 range indicate errors that have been caused by the requesting application (e.g., a malformed request body has been sent). Retrying such requests with the same request body is pointless and will result in the same status code again. Some 4xx errors can be handled programmatically. The error response is in JSON format and is structured like this:

{
  "status_code": 400,
  "error": "Bad Request",
  "code": "E_SOME_ERROR",
  "message": "Something bad happened"
}

The response will contain an error code or other information that reveals the reason for the error. Change the request accordingly before retrying. Below you can find the most frequent errors and how to fix them.

  • 401 Unauthorized
    • E_UNAUTHORIZED_ACCESS
      • Authenticate API
  • 403 Forbidden
    • E_ACCESS_FORBIDDEN
  • 404 Resource does not exist
    • E_ESTABLISHMENT_NOT_FOUND
    • E_TAXPAYER_NOT_FOUND
    • E_TAXPAYER_ADDRESS_NOT_FOUND
    • E_TAXPAYER_PERSON_NOT_FOUND
    • E_SUBMISSION_NOT_FOUND
    • E_CLIENT_NOT_FOUND
    • E_CLIENT_ADDITIONAL_DATA_NOT_FOUND
  • 409 Conflict
  • 423 Locked
    • E_LOCKED_RESOURCE

Status 5xx​

Status codes in the 500-599 range indicate errors on the server side. These errors can be considered temporary.