# Riferimento degli errori

Ogni endpoint dell'API NSE utilizza un insieme coerente di codici di stato HTTP. Questo riferimento descrive il significato di ciascun codice, l'aspetto del corpo della risposta ove applicabile e le azioni da intraprendere quando viene restituito.

## Codici di stato HTTP

### 400 Bad Request

La richiesta non era strutturalmente valida: un campo obbligatorio era assente, un valore era di tipo errato, un valore di enum non è stato riconosciuto oppure un campo non ha superato un controllo di formato (ad esempio una stringa che doveva essere un UUID).

Il corpo della risposta è un oggetto `ErrorsResponse` che contiene una o più voci di errore che identificano esattamente quale campo o regola ha causato il rifiuto.

**Cosa fare:** leggere i dettagli dell'errore nel corpo della risposta. Correggere il payload della richiesta prima di riprovare. Non ripetere la stessa richiesta senza modifiche: fallirà di nuovo.

Cause comuni:

- Un campo obbligatorio è assente (ad esempio `type` mancante su uno stage)
- Un valore di enum ha un uso errato di maiuscole/minuscole o è scritto in modo errato (ad esempio `"signer"` invece di `"Signer"`)
- Un campo UUID contiene un valore che non è un UUID valido
- Un campo data/ora non è in formato ISO 8601


### 401 Unauthorized

La richiesta non includeva un Bearer token valido oppure il token è scaduto.

**Cosa fare:** ottenere un nuovo token JWT e ripetere la richiesta con l'header `Authorization: Bearer {token}` aggiornato. Non ripetere la richiesta con lo stesso token se è scaduto.

### 403 Forbidden

Il token è valido ma l'utente autenticato non ha l'autorizzazione per eseguire questa operazione. In genere ciò significa che l'utente non possiede il ruolo richiesto oppure non appartiene all'organizzazione indicata nel percorso.

**Cosa fare:** verificare che `organizationId` nel percorso della richiesta corrisponda all'organizzazione a cui appartiene l'utente e che l'utente disponga delle autorizzazioni necessarie. Non si tratta di un errore transitorio: ripetere la richiesta non sarà d'aiuto.

### 404 Not Found

La risorsa indicata nel percorso non esiste. Questo vale per pratiche, stage, destinatari, file e artifact.

**Cosa fare:** verificare che gli ID nel percorso della richiesta siano corretti e che la risorsa sia stata creata correttamente prima di questa chiamata. Un `404` su una risorsa creata di recente può indicare che una precedente chiamata di creazione è fallita silenziosamente oppure che si sta utilizzando l'ID errato.

### 422 Unprocessable Content

La richiesta era strutturalmente valida ma non ha potuto essere eseguita a causa della violazione di una regola di business. L'entità esiste e la richiesta è ben formata, ma l'operazione non è consentita nello stato attuale.

Il corpo della risposta è un oggetto `ErrorsResponse` con i dettagli sulla regola violata.

**Cosa fare:** leggere i dettagli dell'errore. La correzione dipende dalla regola specifica; gli scenari più comuni comprendono:

- Il tentativo di modificare una pratica già inviata
- Il tentativo di inviare una pratica senza destinatari o senza file
- Il posizionamento di un task di campo per un `recipientId` che non appartiene alla pratica
- Il tentativo di creare una risorsa su una pratica che non è in stato `draft`


### 500 Internal Server Error

Si è verificato un errore inatteso sul lato server. Non è causato dal contenuto della richiesta.

**Cosa fare:** ripetere la richiesta dopo una breve attesa. Se l'errore persiste, indica un problema di piattaforma. Contattare il supporto Namirial fornendo i dettagli della richiesta e il timestamp affinché l'incidente possa essere analizzato.

## Il corpo ErrorsResponse

Le risposte di errore includono un corpo di errore strutturato. Lo schema è denominato `ErrorsResponse` e contiene un elenco di voci di errore che descrivono il problema verificatosi.

> Nota: i nomi esatti dei campi dello schema ErrorsResponse non sono confermati dalla specifica API attuale. Esaminare il corpo della risposta effettivo nella propria integrazione per determinarne la struttura precisa. Il corpo sarà sempre in formato JSON.


## Tabella di riferimento rapido

| Codice | Nome | Correzione necessaria |
|  --- | --- | --- |
| 400 | Bad Request | Correggere il payload della richiesta |
| 401 | Unauthorized | Rinnovare il Bearer token |
| 403 | Forbidden | Verificare l'ID organizzazione e le autorizzazioni dell'utente |
| 404 | Not Found | Verificare che l'ID della risorsa esista |
| 422 | Unprocessable Content | Correggere la violazione della regola di business |
| 429 | Too Many Requests | Implementare un backoff, ridurre la frequenza delle chiamate |
| 500 | Internal Server Error | Riprovare; contattare il supporto se persiste |