Errori e gestione degli errori

Se una richiesta Firestore in modalità Datastore ha esito positivo, l'API restituisce un codice di stato HTTP 200 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 HTTP 4xx o 5xx che identifica genericamente l'errore, nonché una risposta che fornisce informazioni più specifiche sugli errori che hanno causato l'errore.

Il resto della pagina descrive la struttura di un errore, elenca codici di errore specifici e consiglia 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 genericamente l'errore della richiesta.
message Informazioni specifiche sulla richiesta non riuscita.
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 application/x-protobuf restituisce un errore, verrà restituito come payload un messaggio google.rpc.Status serializzato.

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 effettuare la richiesta o struttura le entità per ridurre la contesa.

Per le richieste che fanno parte di un commit transactional:
Riprova l'intera transazione o struttura le tue entità per ridurre la contesa.
ALREADY_EXISTS Indica che la richiesta ha tentato di inserire un'entità già esistente. Non riprovare senza risolvere il problema.
DEADLINE_EXCEEDED È stata superata una scadenza sul server. Riprova utilizzando il backoff esponenziale.
FAILED_PRECONDITION Indica che una condizione preliminare per la richiesta non è stata soddisfatta. Il campo del messaggio nella risposta di errore fornisce informazioni sulla precondizione dell'errore. 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 più di una volta.
INVALID_ARGUMENT Indica che un parametro di richiesta contiene un valore non valido. Il campo del messaggio nella risposta di errore fornisce informazioni su quale valore non era valido. Non riprovare senza risolvere il problema.
NOT_FOUND Indica che la richiesta ha tentato di aggiornare un'entità che non esiste. Non riprovare senza risolvere il problema.
PERMISSION_DENIED Indica che l'utente non era autorizzato a effettuare la richiesta. Non riprovare senza risolvere il problema.
RESOURCE_EXHAUSTED Indica che il progetto ha superato la propria quota o la capacità a livello di regione/più 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 un 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.