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"
}
}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> |
MissingCombination | <Field> is required if <OtherField> is provided |
<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 |
<Method> |
InvalidValue | <Method> is not available for this installation |
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 (1000 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".
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.