L'API segue un approccio strutturato alla gestione degli errori, fornendo feedback significativi quando le richieste falliscono a causa di problemi di validazione, violazioni delle regole di business o altre condizioni impreviste. Sebbene esistano standard interni per la restituzione degli errori, l'implementazione può variare tra le diverse query/mutazioni.
Comportamento della risposta e codici di stato HTTP
Nella maggior parte dei casi, l'API restituisce uno stato HTTP 200 OK anche quando si verifica un errore. Questo perché gli errori GraphQL vengono gestiti all'interno del corpo della risposta invece che tramite i codici di stato HTTP. Una delle eccezioni è il codice di stato 429 - Troppe richieste, che viene restituito quando si superano i limiti di frequenza. Possono essere utilizzati anche altri codici di stato, come quelli che indicano problemi di autenticazione o di disponibilità.
Errori di validazione
Se l'input non soddisfa i requisiti previsti, ad esempio quando non vengono rispettate le regole di business, la risposta includerà un elenco di errori di validazione. Per le mutazioni che eseguono la validazione dell'input, la risposta segue generalmente questa struttura:
type UpdateActivityResult {
validationErrors: [ValidationErrors]
item: Activity
}Quando la validazione fallisce, la proprietà item viene solitamente impostata sul suo valore predefinito e la proprietà validationErrors fornisce dettagli sul problema. Il campo message offre indicazioni utili su come procedere.
Esempio: risposta di errore di validazione
{
"data": {
"updateActivity": {
"item": null,
"validationErrors": [
{
"message": "ActivityDate deve essere nel formato 'yyyy-MM-dd HH:mm:ss'",
"propertyName": "ActivityDate"
}
]
}
}
}Errori generali
Gli errori non legati alla validazione, come i fallimenti interni di elaborazione, problemi con servizi esterni o condizioni impreviste, vengono restituiti nella collection errors della risposta GraphQL.
Questi errori includono solitamente:
- Messaggio: Una descrizione dell'errore.
- Estensioni: Metadati aggiuntivi come codici di errore o informazioni contestuali.
Esempio: risposta di errore generale
{
"data": {
"addActivity": null
},
"errors": [
{
"message": "La richiesta del metodo non è riuscita con [220] Il formato del timestamp deve essere yyyy-mm-dd hh:mm:ss[.fffffffff] per addActivity",
"extensions": {
"code": "APP_SERVER_METHOD",
"data": {
"activityId": "00-ebaa2c159c436a4a8e4c6bd086e33b2b-4927fca7e17ec948-00"
}
}
}
]
}Considerazioni
- Sebbene gli standard sopra descritti siano generalmente seguiti, alcune query/mutazioni potrebbero non essere ancora completamente allineate. Il Third-Party Client dovrebbe gestire sia gli errori di validazione strutturati che gli errori generali GraphQL in modo appropriato.
- Il Third-Party Client dovrebbe sempre controllare il corpo della risposta per i dettagli sugli errori invece di affidarsi solo ai codici di stato HTTP.