L'API Calendar restituisce due livelli di informazioni sugli errori:
- Codici di errore HTTP e messaggi nell'intestazione
- Un oggetto JSON nel corpo della risposta con dettagli aggiuntivi che possono aiutarti a determinare come gestire l'errore.
Il resto di questa pagina fornisce un riferimento agli errori di Calendar e alcune linee guida su come gestirli nella tua app.
Implementare il backoff esponenziale
La documentazione sulle API Cloud contiene una buona spiegazione del backoff esponenziale e di come utilizzarlo con le API di Google.
Errori e azioni suggerite
Questa sezione fornisce la rappresentazione JSON completa di ogni errore elencato e le azioni suggerite che puoi intraprendere per gestirlo.
400: Richiesta non valida
Errore utente. Ciò può significare che un campo o un parametro obbligatorio non è stato fornito, il valore fornito non è valido o la combinazione dei campi forniti non è valida.
{
"error": {
"errors": [
{
"domain": "calendar",
"reason": "timeRangeEmpty",
"message": "The specified time range is empty.",
"locationType": "parameter",
"location": "timeMax",
}
],
"code": 400,
"message": "The specified time range is empty."
}
}
Azione suggerita:poiché si tratta di un errore permanente, non riprovare. Leggi il messaggio di errore e modifica la richiesta di conseguenza.
401: credenziali non valide
Intestazione di autorizzazione non valida. Il token di accesso che stai utilizzando è scaduto o non è valido.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
Azioni suggerite:
- Ottieni un nuovo token di accesso utilizzando il token di aggiornamento di lunga durata.
- Se questa operazione non riesce, indirizza l'utente attraverso il flusso OAuth, come descritto in Autorizzazione delle richieste con OAuth 2.0.
- Se vedi questo messaggio per un account di servizio, verifica di aver completato correttamente tutti i passaggi nella pagina dell'account di servizio.
403: Limite di frequenza utenti superato
È stato raggiunto uno dei limiti della Developer Console.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Azioni suggerite:
- Assicurati che la tua app segua le best practice della sezione Gestisci le quote.
- Aumenta la quota per utente nel progetto della Developer Console.
- Se un utente invia numerose richieste per conto di molti utenti di un account Google Workspace, valuta la possibilità di utilizzare un account di servizio con delega a livello di dominio e impostare il parametro
quotaUser
. - Utilizza il backoff esponenziale.
403: Limite di frequenza superato
L'utente ha raggiunto il numero massimo di richieste dell'API Google Calendar per calendario o per utente autenticato.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "rateLimitExceeded",
"message": "Rate Limit Exceeded"
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Azione suggerita:gli errori rateLimitExceeded
possono restituire codici di errore 403 o 429; al momento sono simili dal punto di vista funzionale e devono essere risposte
allo stesso modo utilizzando il backoff esponenziale.
Inoltre, assicurati che la tua app segua le best practice della sezione Gestione delle quote.
403: limiti di utilizzo di Calendar superati
L'utente ha raggiunto uno dei limiti di Google Calendar applicati per proteggere gli utenti e l'infrastruttura Google da comportamenti illeciti.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Calendar usage limits exceeded.",
"reason": "quotaExceeded"
}
],
"code": 403,
"message": "Calendar usage limits exceeded."
}
}
Azioni suggerite:
- Per saperne di più sui limiti di utilizzo di Calendar, consulta il Centro assistenza per amministratori di Google Workspace.
403: Vietato ai non organizzatori
La richiesta di aggiornamento dell'evento sta tentando di impostare una delle proprietà dell'evento condiviso in una copia che non appartiene all'organizzatore. Le proprietà condivise (ad esempio, guestsCanInviteOthers
, guestsCanModify
o guestsCanSeeOtherGuests
) possono essere impostate solo dall'organizzatore.
{
"error": {
"errors": [
{
"domain": "calendar",
"reason": "forbiddenForNonOrganizer",
"message": "Shared properties can only be changed by the organizer of the event."
}
],
"code": 403,
"message": "Shared properties can only be changed by the organizer of the event."
}
}
Azioni suggerite:
- Se utilizzi Eventi: inserimento, Eventi: importazione o Eventi: aggiornamento e la richiesta non include proprietà condivise, equivale a tentare di impostarle sui valori predefiniti. Prendi in considerazione l'utilizzo di Events: patch.
- Se la tua richiesta ha proprietà condivise, assicurati di provare a modificarle solo se stai aggiornando la copia dell'organizzatore.
404: Non trovato
La risorsa specificata non è stata trovata. Questo può accadere in diversi casi. Ecco alcuni esempi:
- Quando la risorsa richiesta (con l'ID fornito) non è mai esistita
quando accede a un calendario a cui l'utente non può accedere
{ "error": { "errors": [ { "domain": "global", "reason": "notFound", "message": "Non trovato" } ], "code": 404, "message": "Non trovato" } }
Azione suggerita:utilizza il backoff esponenziale.
409: l'identificatore richiesto esiste già
Un'istanza con l'ID specificato esiste già nello spazio di archiviazione.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "duplicate",
"message": "The requested identifier already exists."
}
],
"code": 409,
"message": "The requested identifier already exists."
}
}
Azione suggerita: genera un nuovo ID se vuoi creare una nuova istanza, altrimenti utilizza la chiamata al metodo update.
410: Fine
I parametri syncToken
o updatedMin
non sono più validi. Questo errore può verificarsi anche se una richiesta tenta di eliminare un evento che è già stato eliminato.
{
"error": {
"errors": [
{
"domain": "calendar",
"reason": "fullSyncRequired",
"message": "Sync token is no longer valid, a full sync is required.",
"locationType": "parameter",
"location": "syncToken",
}
],
"code": 410,
"message": "Sync token is no longer valid, a full sync is required."
}
}
o
{
"error": {
"errors": [
{
"domain": "calendar",
"reason": "updatedMinTooLongAgo",
"message": "The requested minimum modification time lies too far in the past.",
"locationType": "parameter",
"location": "updatedMin",
}
],
"code": 410,
"message": "The requested minimum modification time lies too far in the past."
}
}
o
{
"error": {
"errors": [
{
"domain": "global",
"reason": "deleted",
"message": "Resource has been deleted"
}
],
"code": 410,
"message": "Resource has been deleted"
}
}
Azione suggerita: per i parametri syncToken
o updatedMin
, cancella l'archivio e ripeti la sincronizzazione. Per ulteriori dettagli, consulta Sincronizzazione efficiente delle risorse.
Per gli eventi già eliminati, non sono necessarie ulteriori azioni.
412: condizione preliminare non riuscita
L'etag fornito nell'intestazione If-match non corrisponde più all'etag attuale della risorsa.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "conditionNotMet",
"message": "Precondition Failed",
"locationType": "header",
"location": "If-Match",
}
],
"code": 412,
"message": "Precondition Failed"
}
}
Azione suggerita: recupera nuovamente l'entità e applica nuovamente le modifiche. Per maggiori dettagli, consulta Ottenere versioni specifiche delle risorse.
429: Troppe richieste
Si verifica un errore rateLimitExceeded
quando l'utente ha inviato troppe richieste in un determinato periodo di tempo.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "rateLimitExceeded",
"message": "Rate Limit Exceeded"
}
],
"code": 429,
"message": "Rate Limit Exceeded"
}
}
Azione suggerita:gli errori rateLimitExceeded
possono restituire codici di errore 403 o 429; al momento sono simili dal punto di vista funzionale e devono essere risposte
allo stesso modo utilizzando il backoff esponenziale.
Inoltre, assicurati che la tua app segua le best practice della sezione Gestione delle quote.
500: errore del backend
Si è verificato un errore imprevisto durante l'elaborazione della richiesta.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
Azione suggerita:utilizza il backoff esponenziale.