Errori e codici di stato

Validazione interna

Gli errori di validazione interna si verificano quando i dati inviati in una richiesta non sono conformi al formato o allo schema previsto definito dall’API. Ad esempio, se un campo si aspetta un tipo di valore specifico, come una particolare enumerazione (p. es., “1” per Herr, “2” per Frau, “3” per Divers) o una struttura richiesta, qualsiasi discrepanza rispetto a questo attiverà un errore di validazione.

Validazione esterna

Nel caso in cui la validazione esterna tramite ERiC/ELSTER fallisca, il messaggio di errore può essere recuperato tramite l’endpoint Download ERiC/ELSTER transmission XML. Si noti che l’XML può contenere più errori.

Importante: L’XML è la risposta grezza inviata da ERiC/ELSTER. L’API SIGN DE x Submission di fiskaly non interpreta la risposta.

Stato 2xx

I codici di stato nell’intervallo 200–299 indicano il successo.

Stato 4xx

I codici di stato nell’intervallo 400–499 indicano errori causati dall’applicazione richiedente (p. es., è stato inviato un corpo della richiesta non valido). Ripetere tali richieste con lo stesso corpo della richiesta è inutile e restituirà lo stesso codice di stato. Alcuni errori 4xx possono essere gestiti in modo programmatico. La risposta di errore è in formato JSON ed è strutturata in questo modo:

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

La risposta conterrà un codice di errore o altre informazioni che rivelano il motivo dell’errore. Modificare la richiesta di conseguenza prima di riprovare. Di seguito sono riportati gli errori più frequenti e come risolverli.

• 401 Unauthorized
  • E_UNAUTHORIZED_ACCESS
    • Autenticare l’API
• 403 Forbidden
  • E_ACCESS_FORBIDDEN
• 404 La risorsa non esiste
  • 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

Stato 5xx

I codici di stato nell’intervallo 500–599 indicano errori lato server. Questi errori possono essere considerati temporanei.