Errori e gestione degli errori

Quando una richiesta di Firestore in modalità Datastore va a buon fine, l'API restituisce un codice di stato HTTP200 OK insieme ai dati richiesti nel corpo della risposta.

Quando una richiesta non va a buon fine, l'API Datastore restituisce un codice di stato HTTP4xx o 5xx che identifica in modo generico l'errore, nonché una risposta che fornisce informazioni più specifiche sugli errori che hanno causato l'errore.

Nel resto di questa pagina viene descritta la struttura di un errore, vengono elencati codici di errore specifici e vengono forniti consigli su come gestirli.

Di seguito è riportata la struttura di una risposta di errore per una richiesta JSON:

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

L'oggetto 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 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 Datastore sono elencati in Codici di errore.

Ecco un esempio di risposta di errore per una richiesta JSON:

{
  "error": {
    "code": 400,
    "message": "Key path is incomplete: [Person: null]",
    "status": "INVALID_ARGUMENT"
  }
}

Se una richiesta effettuata con un tipo di contenuto application/x-protobuf genera un errore, verrà restituito un messaggio google.rpc.Status serializzato come payload.

Codici di errore

Il modo consigliato per classificare gli errori è controllare il valore del codice di errore canonico (google.rpc.Code). Negli errori JSON, questo codice viene visualizzato nel campo status. Negli errori application/x-protobuf, si trova nel campo code.

Codice di errore canonico Descrizione Azione consigliata
ABORTED Indica che la richiesta è in conflitto con un'altra richiesta. Per un commit non transazionale:
riprova a inviare la richiesta o organizza le entità per ridurre le contese.

Per le richieste che fanno parte di un commit transazionale:
riprova a inviare l'intera transazione o organizza le entità per ridurre le contese.
ALREADY_EXISTS Indica che la richiesta ha tentato di inserire un'entità già esistente. Non riprovare senza risolvere il problema.
DEADLINE_EXCEEDED Una scadenza è stata superata sul server. Riprova utilizzando il backoff esponenziale.
FAILED_PRECONDITION Indica che una precondizione per la richiesta non è stata soddisfatta. Il campo messaggio nella risposta all'errore fornisce informazioni sul precondizionatore non riuscito. Una possibile causa è l'esecuzione di una query che richiede un indice non ancora definito. Non riprovare senza risolvere il problema.
INTERNAL Il server ha restituito un errore. Non riprovare a inviare questa richiesta più di una volta.
INVALID_ARGUMENT Indica che un parametro di richiesta ha un valore non valido. Il campo messaggio nella risposta all'errore fornisce informazioni sul valore non valido. Non riprovare senza risolvere il problema.
NOT_FOUND Indica che la richiesta ha tentato di aggiornare un'entità inesistente. Non riprovare senza risolvere il problema.
PERMISSION_DENIED Indica che l'utente non era autorizzato a inviare la richiesta. Non riprovare senza risolvere il problema.
RESOURCE_EXHAUSTED Indica che il progetto ha superato la quota o la capacità della regione/delle regioni. Verifica di non aver superato la quota del progetto. Se hai superato una quota del progetto, non riprovare senza risolvere il problema.

In caso contrario, riprova con il backoff esponenziale.
UNAUTHENTICATED Indica che la richiesta non aveva credenziali di autenticazione valide. Non riprovare senza risolvere il problema.
UNAVAILABLE Il server ha restituito un errore. Riprova utilizzando il backoff esponenziale.