Gestire gli errori dell'API

L'API Google Calendar restituisce due livelli di informazioni sugli errori:

  • Codici e messaggi di errore HTTP 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, con alcune indicazioni su come gestirli nella tua app.

Implementare il backoff esponenziale

La documentazione di Google Cloud Storage spiega il backoff esponenziale e 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 potresti intraprendere per gestirlo.

400: Richiesta non valida

Errore utente. Questo errore si verifica quando non fornisci un campo o un parametro obbligatorio, fornisci un valore non valido o una combinazione di campi 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 invece 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 a lunga durata.
  • Se non funziona, guida l'utente attraverso il flusso OAuth, come descritto in Autorizzare le richieste con OAuth 2.0.
  • Se questo errore si verifica per un account di servizio, verifica di aver completato correttamente tutti i passaggi nella pagina dell'account di servizio.

403: Limite di frequenza per utente superato

È stato raggiunto uno dei limiti della console Google Cloud.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "userRateLimitExceeded",
        "message": "User Rate Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "User Rate Limit Exceeded"
  }
}

Azioni suggerite:

403: Limite di frequenza superato

L'utente ha raggiunto la frequenza massima di richieste dell'API 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: rateLimitExceeded errori possono restituire i codici di errore 403 o 429 Sono funzionalmente simili e devi gestirli allo stesso modo, utilizzando il backoff esponenziale. Inoltre, assicurati che la tua app segua le best practice per la gestione delle quote.

403: Limiti di utilizzo di Calendar superati

L'utente ha raggiunto uno dei limiti di Calendar in vigore per proteggere gli utenti e l'infrastruttura di Google da comportamenti illeciti.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "message": "Calendar usage limits exceeded.",
        "reason": "quotaExceeded"
      }
    ],
    "code": 403,
    "message": "Calendar usage limits exceeded."
  }
}

Azioni suggerite:

403: Accesso negato per i non organizzatori

La richiesta di aggiornamento dell'evento sta tentando di impostare una delle proprietà dell'evento condiviso in una copia che non è quella dell'organizzatore. Solo l'organizzatore può impostare le proprietà condivise (ad esempio, guestsCanInviteOthers, guestsCanModify o guestsCanSeeOtherGuests).

{
  "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: inserisci, Eventi: importa o Eventi: aggiorna, e la tua richiesta non include proprietà condivise, equivale a tentare di impostarle sui valori predefiniti. Valuta la possibilità di utilizzare Eventi: patch invece.
  • Se la tua richiesta ha proprietà condivise, assicurati di provare a modificare queste proprietà solo se stai aggiornando la copia dell'organizzatore.

404: Non trovata

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 si accede a un calendario a cui l'utente non può accedere.
{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "Not Found"
      }
    ],
    "code": 404,
    "message": "Not Found"
  }
}

Azione suggerita: utilizza il backoff esponenziale.

409: L'identificatore richiesto esiste già

Esiste già un'istanza con l'ID specificato nell'archivio.

{
  "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; in caso contrario, utilizza il events.update metodo.

409: Conflitto

Un elemento in batch all'interno di un events.batch operazione non può essere eseguito a causa di un conflitto operativo con altri elementi in batch richiesti.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "conflict",
        "message": "Conflict"
      }
    ],
    "code": 409,
    "message": "Conflict"
  }
}

Azione suggerita: rimuovi gli elementi completati e non riusciti, quindi riprova a eseguire gli elementi rimanenti in un'operazione events.batch diversa o nelle operazioni di singoli eventi corrispondenti.

410: Non più disponibile

I parametri syncToken o updatedMin non sono più validi. Questo errore può verificarsi anche se una richiesta tenta di eliminare un evento già 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 sincronizza di nuovo. Per maggiori dettagli, consulta Sincronizzare le risorse in modo efficiente. Per gli eventi già eliminati, non è necessaria alcuna ulteriore azione.

412: Precondizione non riuscita

L'ETag fornito nell'intestazione If-Match non corrisponde più all'ETag corrente della risorsa.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "conditionNotMet",
        "message": "Precondition Failed",
        "locationType": "header",
        "location": "If-Match"
      }
    ],
    "code": 412,
    "message": "Precondition Failed"
  }
}

Azione suggerita: recupera di nuovo l'entità e riapplica le modifiche. Per maggiori dettagli, consulta Recuperare 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: rateLimitExceeded errori possono restituire i codici di errore 403 o 429 Sono funzionalmente simili e devi gestirli allo stesso modo, utilizzando il backoff esponenziale. Inoltre, assicurati che la tua app segua le best practice per la gestione delle quote.

500: Errore nel 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.