Codes d'erreur et gestion des exceptions Spanner

Cette page décrit les codes d'erreur Spanner et les actions recommandées pour gérer ces erreurs. Les API Google, y compris Spanner, utilisent le codes d'erreur canoniques définis par google.rpc.Code.

Lorsqu'une requête Spanner aboutit, l'API renvoie une réponse Code d'état 200 OK, ainsi que les données demandées dans le corps de la réponse.

Lorsqu'une requête échoue, l'API Spanner renvoie une réponse Code d'état 4xx ou 5xx qui identifie l'échec de manière générique, ainsi qu'un une réponse qui fournit des informations plus spécifiques sur les erreurs à l'origine de l'échec.

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 que l'API Spanner peut renvoyer sont répertoriés dans la section Codes d'erreur.

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 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 Description Action recommandée
ABORTED L'opération a été annulée, généralement en raison d'un problème de simultanéité, tel qu'un échec de vérification du séquenceur ou un abandon de transaction. 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 L'entité qu'un client a tenté de créer existe déjà (par exemple, l'insertion d'une ligne avec une clé primaire existante). Ne relancez pas la requête avant d'avoir résolu le problème.
CANCELLED L'opération a été annulée, généralement par l'appelant. Effectuez une nouvelle tentative.
DEADLINE_EXCEEDED Le délai a expiré avant que l'opération puisse se terminer. Vérifiez si le délai est suffisant. Utilisez un délai correspondant à l'heure réelle à laquelle une réponse est utile. Notez que pour les opérations qui modifient l'état du système, une erreur peut être renvoyée même si l'opération s'est terminée avec succès.

Pour obtenir des conseils, consultez Résoudre les erreurs de dépassement de délai.
FAILED_PRECONDITION L'opération a été rejetée, car 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é. Par exemple, vous pouvez lire ou interroger des données à partir d'un horodatage dont le délai d'obsolescence maximal est dépassé. Ne relancez pas la requête avant d'avoir résolu le problème.
INTERNAL Le serveur a renvoyé une erreur. Certaines invariantes attendues par le système sous-jacent ne fonctionnent pas. Ne faites de nouvelles tentatives que si vous comprenez les circonstances et la cause de l'erreur.
INVALID_ARGUMENT Le client a spécifié 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 qu'une entité demandée, telle que la mise à jour d'une entité ou l'interrogation d'une table ou d'une colonne, n'existe pas. Ne relancez pas la requête avant d'avoir résolu le problème.
OUT_OF_RANGE L'opération a été tentée au-delà de la plage valide. Ne relancez pas la requête avant d'avoir résolu le problème.
PERMISSION_DENIED L'utilisateur n'a pas été autorisé à effectuer cette requête. Ne relancez pas la requête avant d'avoir résolu le problème.
RESOURCE_EXHAUSTED Une ressource est épuisée. Il se peut que le projet ait dépassé son quota ou que l'espace soit saturé dans l'ensemble du système de fichiers. Vérifiez que vous n'avez pas dépassé votre quota Spanner ou celui du projet. Si vous avez dépassé un quota, n'effectuez aucune nouvelle tentative avant d'avoir résolu le problème.

Sinon, réessayez avec un intervalle exponentiel entre les tentatives.
UNAUTHENTICATED La requête ne dispose pas d'identifiants d'authentification valides pour l'opération. Ne relancez pas la requête avant d'avoir résolu le problème.
UNAVAILABLE Le serveur est indisponible. Relancez la requête avec un intervalle exponentiel entre les tentatives. Notez qu'il n'est pas toujours sûr de relancer des opérations non idempotentes.
UNIMPLEMENTED L'opération n'est pas implémentée ou n'est pas prise en charge/activée dans ce service. Ne relancez pas la requête avant d'avoir résolu le problème.
UNKNOWN Le serveur a renvoyé une erreur inconnue. Les erreurs générées par des API qui ne renvoient pas suffisamment d'informations sur les erreurs peuvent être converties en cette erreur. Vérifiez que votre requête est sécurisée. Réessayez ensuite avec un intervalle exponentiel entre les tentatives.