Gestione degli errori

Durante l'uso dell'API si possono verificare degli errori che possono essere dovuti ad un errore nella vostra applicazione come ad esempio "il metodo non esiste", "manca un parametro" oppure "il parametro non è corretto" oppure ad una impossibilità momentanea per il server di soddisfare la richiesta, ad esempio "troppe richieste" oppure "errore interno al sistema".

In questi casi la risposta riporta nel campo status il valore "error" e nel campo error il motivo dell'errore. Ad esempio:

  200 OK

{
  "status" : "error",
  "error" : {
    "field" : "name",
    "type" : "Malformed",
    "description" : "Name is not syntactically correct"
  }
}

Errori comuni

I seguenti sono errori che si possono verificare in tutte le chiamate e sono dovuti alla vostra applicazione. In genere questi errori indicano che esiste un errore nel codice dell'applicazione che deve essere corretto ad esempio se non sono state fatte le dovute verifiche sulla sintassi dei valori dei parametri prima di chiamare il metodo.

Field Type Description
unknown UnknownField Field '<Field>' is unknown
<Field> AccessDenied Access denied to field <Field>
<Field> Missing <Field> is required
<Field> Malformed <Field> is not syntactically correct
<Field> InvalidValue <Field> is not a valid value
<Field> InvalidCombination <Field> is not allowed if <OtherField> is provided

Altri errori

Ci sono casi in cui il server riceve la richiesta ma non la può elaborare in quanto ad esempio il metodo HTTP non è POST, la chiave non è corretta, il metodo dell'API non esiste oppure si è raggiunto il limite massimo di chiamate (200 ogni 5 minuti). In queste situazioni lo stato HTTP sarà diverso da 200 OK e la risposta non sarà in formato JSON. Le seguenti sono gli errori più comuni:

Stato HTTP Soluzione
403 Forbidden, malformed key Utilizzare per l'header HTTP "X-Key" una chiave valida
403 Forbidden, missing key Aggiungere l'header HTTP "X-Key" con la chiave
404 Not Found Cambiare il numero di versione o il metodo riportati nella URL in quanto non esiste
405 Invalid Content-Length header Correggere l'header HTTP "Content-Length" con un numero valido
405 Invalid Content-Type header Utilizzare per l'header HTTP "Content-Type" uno tra "application/json" e "text/javascript"
405 Method Not Allowed Utilizzare il metodo HTTP POST
405 Missing Content-Length header Aggiungere l'header HTTP "Content-Length"
405 Missing Content-Type header Aggiungere l'header HTTP "Content-Type"
400 Bad Request, malformed JSON data Correggere il corpo della richiesta affinché sia JSON
503 Service Unavailable Attendere il numero di secondi indicato nell'header HTTP "X-Wait-Seconds" della risposta

Ci possono poi essere casi in cui il server non riceve la richiesta oppure la vostra applicazione non riceve la risposta, ad esempio in caso di errori dovuti alla rete. In questo caso lo stato HTTP sarà diverso da 200 OK e la risposta non sarà in formato JSON.

Non sono da sottovalutare anche errori che possono generare le librerie utilizzate dalla vostra applicazione per inviare le richieste HTTP come ad esempio "errore nel socket" oppure "il dominio non esiste".

Non seguire i redirect 3xx

Quando si esegue una chiamata HTTP alle API, non si devono mai seguire i redirect, ossia una risposta con stato HTTP 3xx (300, 301, 302, 303, 307) può significare che l'URL nella chiamata non è corretta oppure il server non è configurato correttamente. Consultare la documentazione della libreria che si sta utilizzando per eseguire le chiamate HTTP per sapere come evitare che la libreria segua automaticamente i redirect.