Errori

In questa pagina viene spiegato come gestire gli errori che si possono verificare durante l'utilizzo delle API di Sibill. Le API utilizzano la convenzione per i codici di stato HTTP per indicare il risultato di una richiesta. Gli stati possono essere categorizzati in questo modo:

• Codici 2xx: indicano il successo della richiesta
• Codici 4xx: indicano un errore del client
• Codici 5xx: indicano un errore del server

Ogni errore include un payload che descrive ciò che è accaduto. Di seguito c'è un elenco dei codici di stato HTTP utilizzati dalle API:

Codice HTTP	Significato	Descrizione
200	OK	Tutto ha funzionato come previsto.
201	Created	La risorsa è stata creata con successo.
400	Bad Request	La richiesta non è accettabile, spesso a causa di un parametro richiesto mancante.
401	Unauthorized	Non è stata fornita una chiave API valida.
402	Request Failed	I parametri erano validi, ma la richiesta non è andata a buon fine.
403	Forbidden	La chiave API non ha i permessi per eseguire la richiesta.
404	Not Found	La risorsa richiesta non esiste.
422	Unprocessable Entity	La richiesta è stata compresa ma non può essere elaborata a causa di errori semantici.
500, 502, 503, 504	Server Errors	Si è verificato un problema nella gestione della richiesta da parte di Sibill.

🙅‍♂️ Errori di autenticazione

Utilizzando l'autenticazione basata su token, è possibile ricevere un errore se il token non è valido o non è stato fornito.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
   "errors":[
      {
         "code":"unauthorized",
         "detail":"Authentication failed.",
         "title":"Unauthorized"
      }
   ]
}

Nel caso in cui il token sia valido, ma non abbia i permessi necessari per eseguire la richiesta, riceverai un errore 403.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
   "errors":[
      {
         "code":"forbidden",
         "detail":"Forbidden.",
         "title":"Forbidden"
      }
   ]
}

Per verificare velocemente se il token è valido, si ha l'accesso agli endpoint o se c'è un problema di rete, si pò provare il comando:

curl --request GET \
     --url {{BASE_URL}}/api/v1/companies \
     --header "Authorization: Bearer {{TOKEN}}"

Gli errori dovuti a problemi di convalida includeranno l'oggetto source, che contiene l'elenco dei campi che hanno generato l'errore.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
   "errors":[
      {
         "code":"bad_request",
         "detail":"Invalid integer. Got: string",
         "title":"Invalid value",
         "source":{
            "pointer":"/page_size"
         }
      }
   ]
}

🖥️ Errori del server di Sibill

Altri errori che non sono causati da problemi di autenticazione o di richiesta del client, ma da problemi interni del server, generano una risposta con un oggetto errore che descrive il problema.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
   "errors":[
      {
         "code":"internal_server_error",
         "detail":"An unexpected error occurred.",
         "title":"Internal Server Error"
      }
   ]
}