Messaggi di errore

Quando una richiesta API Cloud IoT Core di Google Cloud ha esito positivo, l'API restituisce un codice di stato 200 OKHTTP insieme ai dati richiesti nel corpo della risposta.

Quando una richiesta non va a buon fine, l'API Cloud IoT Core restituisce un codice di stato HTTP 4xx o 5xx che identifica in modo generico l'errore, oltre a una risposta che fornisce informazioni più specifiche sull'errore che ha causato l'errore.

Nella parte restante di questa pagina viene descritta la struttura di un errore, vengono elencati specifici codici di errore e viene consigliato come gestirli.

Le risposte agli errori per le richieste JSON hanno la seguente struttura:

{
  "error": {
    "code": "integer",
    "message": "string",
    "status": "string",
    "details": array
  }
}

L'oggetto di risposta contiene un singolo campo error il cui valore contiene i seguenti elementi:

Elemento	Descrizione
`code`	Un codice di stato HTTP che identifica in modo generico l'errore della richiesta.
`message`	Informazioni specifiche di Cloud IoT Core sull'errore della richiesta.
`status`	Il codice di errore canonico (`google.rpc.Code`) per le API di Google. I codici che possono essere restituiti dall'API Cloud IoT Core sono elencati in Codici di errore.
`details`	Informazioni aggiuntive, come il tipo di errore e/o una descrizione più dettagliata della causa.

L'esempio seguente mostra una risposta di errore. È stato restituito l'errore perché la richiesta, in questo caso devices.publishEvent, conteneva un payload non valido:

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'binary_data' (TYPE_BYTES), Base64 decoding failed for \"123\"",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "binary_data",
            "description": "Invalid value at 'binary_data' (TYPE_BYTES), Base64 decoding failed for \"123\""
          }
        ]
      }
    ]
  }
}

Codici e gestione degli errori

Il metodo consigliato per classificare gli errori è esaminando il valore del codice di errore canonico (google.rpc.Code). Negli errori JSON, il codice viene visualizzato nel campo status. In errori application/x-protobuf, si trova nel campo code. Per molti errori, l'azione consigliata è tentare nuovamente la richiesta utilizzando il backoff esponenziale. Per informazioni su come implementare il backoff esponenziale in Cloud IoT Core, vedi Implementare il backoff esponenziale.

Codice di errore canonico	Descrizione	Azione consigliata
`ABORTED`	La richiesta era in conflitto con un'altra richiesta.	Riprova utilizzando il backoff esponenziale.
`ALREADY_EXISTS`	La richiesta ha tentato di creare un'entità già esistente.	Non riprovare senza risolvere il problema.
`CANCELLED`	L'operazione è stata annullata, probabilmente dal chiamante.	Riprova utilizzando il backoff esponenziale.
`DEADLINE_EXCEEDED`	È stata superata una scadenza sul server.	Riprova utilizzando il backoff esponenziale.
`FAILED_PRECONDITION`	Una condizione per la richiesta non è stata soddisfatta. Il campo del messaggio nella risposta di errore fornisce informazioni sulla condizione preliminare che non è riuscita.	Non riprovare senza risolvere il problema.
`INTERNAL`	Il server ha restituito un errore.	Riprova utilizzando il backoff esponenziale.
`INVALID_ARGUMENT`	Il client ha specificato un argomento non valido.	Non riprovare senza risolvere il problema.
`NOT_FOUND`	La richiesta è stata tentata su un'entità che non esiste.	Non riprovare senza risolvere il problema.
`OUT_OF_RANGE`	La richiesta ha superato l'intervallo valido.	Non riprovare senza risolvere il problema.
`PERMISSION_DENIED`	L'utente non era autorizzato a inviare la richiesta. Per evitare di rivelare l'esistenza di risorse, se l'utente effettua una richiesta non autorizzata su un'entità che non esiste, viene restituito questo errore anziché `NOT_FOUND`.	Non riprovare senza risolvere il problema.
`RESOURCE_EXHAUSTED`	Quota di risorse esaurita o vicina alla limitazione della frequenza. Per ulteriori informazioni, consulta l'articolo Applicazione della quota.	Non riprovare senza risolvere il problema.
`UNAVAILABLE`	Il server ha restituito un errore.	Riprova utilizzando il backoff esponenziale.
`UNIMPLEMENTED`	L'operazione non è implementata o non è supportata nell'API Cloud IoT Core.	Non riprovare.
`UNKNOWN`	Errore sconosciuto.	Riprova utilizzando il backoff esponenziale.