Erreurs et traitement des erreurs

Lorsqu'une requête Firestore en mode Datastore aboutit, l'API renvoie un code d'état HTTP 200 OK avec les données demandées dans le corps de la réponse.

Lorsqu'une requête échoue, l'API Datastore renvoie un code d'état HTTP 4xx ou 5xx qui identifie l'échec de manière générique, ainsi qu'une réponse fournissant des informations plus spécifiques sur les erreurs ayant causé l'échec.

Le reste de cette page décrit la structure d'une erreur, énumère des codes d'erreur spécifiques et donne des conseils concernant leur gestion.

Voici la structure d'une réponse d'erreur pour une requête JSON :

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

L'objet de la réponse contient un seul champ error dont la valeur contient les éléments suivants :

Élément Description
code Un code d'état HTTP identifiant de manière générique l'échec de la requête.
message Des informations spécifiques au sujet de la requête.
status Le code d'erreur canonique (google.rpc.Code) pour les API Google. Les codes renvoyés par l'API Cloud Datastore sont répertoriés dans la section Codes d'erreur.

Voici un exemple de réponse d'erreur pour une requête JSON :

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

Si une requête effectuée avec un type de contenu application/x-protobuf génère une erreur, elle renvoie un message sérialisé google.rpc.Status en tant que charge utile.

Codes d'erreur

La méthode recommandée pour classer les erreurs consiste à inspecter la valeur du code d'erreur canonique (google.rpc.Code). Dans les erreurs JSON, ce code apparaît dans le champ status. Dans les erreurs application/x-protobuf, il se trouve dans le champ code.

Code d'erreur canonique Description Action recommandée
ABORTED Indique que la requête entre en conflit avec une autre requête. Pour une validation non transactionnelle :
réessayez la requête ou restructurez vos entités pour réduire la contention.

Pour les requêtes faisant partie d'un commit transactionnel :
réessayez l'intégralité de la transaction ou restructurez vos entités afin de réduire la contention.
ALREADY_EXISTS Indique que la requête a tenté d'insérer une entité qui existe déjà. Ne relancez pas la requête avant d'avoir résolu le problème.
DEADLINE_EXCEEDED Un délai a été dépassé sur le serveur. Relancez la requête avec un intervalle exponentiel entre les tentatives.
FAILED_PRECONDITION Indique qu'une condition préalable à la requête n'a pas été remplie. Le champ "message" dans la réponse d'erreur fournit des informations sur la condition préalable ayant échoué. L'une des causes possibles peut être due à l'exécution d'une requête nécessitant un index pas encore défini. Ne relancez pas la requête avant d'avoir résolu le problème.
INTERNAL Le serveur a renvoyé une erreur. Ne relancez pas cette requête plus d'une fois.
INVALID_ARGUMENT Indique qu'un paramètre de requête inclut une valeur non valide. Le champ "message" dans la réponse d'erreur fournit des informations au sujet de la valeur non valide. Ne relancez pas la requête avant d'avoir résolu le problème.
NOT_FOUND Indique que la requête a tenté de mettre à jour une entité qui n'existe pas. Ne relancez pas la requête avant d'avoir résolu le problème.
PERMISSION_DENIED Indique que l'utilisateur n'était pas autorisé à effectuer la requête. Ne relancez pas la requête avant d'avoir résolu le problème.
RESOURCE_EXHAUSTED Indique que le projet a dépassé son quota ou la capacité régionale/multi-régionale. Vérifiez que vous n'avez pas dépassé le quota de votre projet. Si vous avez dépassé le quota d'un projet, ne relancez pas la requête avant d'avoir résolu le problème.

Sinon, relancez la requête avec un intervalle exponentiel entre les tentatives.
UNAUTHENTICATED Indique que la requête ne dispose pas d'identifiants d'authentification valides. Ne relancez pas la requête avant d'avoir résolu le problème.
UNAVAILABLE Le serveur a renvoyé une erreur. Relancez la requête avec un intervalle exponentiel entre les tentatives.