Cette page décrit les codes d'erreur Spanner et les actions recommandées pour les gérer. Les API Google, y compris Spanner, utilisent les codes d'erreur canoniques définis par google.rpc.Code.
Lorsqu'une requête Spanner 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 Spanner 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.
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 Spanner 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 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 | Description | Action recommandée |
|---|---|---|
ABORTED |
L'opération a été abandonné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 essayé de créer existe déjà (par exemple, 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 l'échéance est suffisante. Utilisez une échéance correspondant au délai réel dans lequel 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 la section Résoudre les erreurs liées au dépassement du délai. |
FAILED_PRECONDITION |
L'opération a été refusé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, la lecture ou l'interrogation à partir d'un code temporel ayant dépassé l'obsolescence maximale du code temporel. | Ne relancez pas la requête avant d'avoir résolu le problème. |
INTERNAL |
Le serveur a renvoyé une erreur. Certains invariants attendus par le système sous-jacent n'ont pas été respectés. | Ne réessayez pas tant que vous n'avez pas compris les circonstances et la cause spécifiques 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 (par exemple, 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'était pas autorisé à effectuer la requête. | Ne relancez pas la requête avant d'avoir résolu le problème. |
RESOURCE_EXHAUSTED |
Certaines ressources ont été épuisées. Pour le plan administrateur, il est possible que le projet ait dépassé son quota ou que le système de fichiers dans son intégralité manque d'espace. Pour le plan de données, cela peut se produire si vos nœuds Spanner sont surchargés. |
Pour le plan administrateur, vérifiez que vous n'avez pas dépassé votre quota Spanner ou de projet. Si vous avez dépassé un quota, demandez une augmentation de quota ou attendez que le quota soit réinitialisé avant de réessayer. Configurez vos nouvelles tentatives pour qu'elles utilisent l'intervalle exponentiel entre les tentatives. Pour le plan de données, vérifiez que vos nœuds Spanner n'ont pas dépassé leur capacité. Spanner réessaie ces erreurs dans la bibliothèque cliente. Si toutes les tentatives échouent, consultez la section Erreurs du mécanisme de contrôle de flux. En règle générale, si votre application rencontre des erreurs RESOURCE_EXHAUSTED, traitez la situation comme une erreur UNAVAILABLE et 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. |
Erreurs du mécanisme de contrôle de flux
Spanner peut activer son mécanisme de contrôle de flux pour se protéger contre la surcharge dans les conditions suivantes:
- L'utilisation du processeur est élevée sur le nœud Spanner. Si vous pensez que votre requête entraîne une utilisation élevée du processeur, vous pouvez utiliser les métriques d'utilisation du processeur pour examiner le problème.
- Il peut y avoir des points chauds, ce qui augmente le temps de traitement de la requête. Si vous pensez que votre requête est à l'origine de hotspots, consultez Rechercher des hotspots dans votre base de données pour examiner le problème. Pour en savoir plus, consultez la page Visualiseur de clés.
Le mécanisme de contrôle de flux est compatible avec les bibliothèques clientes suivantes:
Le temps total nécessaire à l'exécution de la requête n'augmentera pas en raison de l'utilisation du mécanisme de contrôle de flux. Sans ce mécanisme, Spanner attend avant de traiter la requête et renvoie finalement une erreur DEADLINE_EXCEEDED.
Lorsque le mécanisme de contrôle de flux est actif, Spanner renvoie les requêtes au client pour qu'il les réessaie. Si la nouvelle tentative consomme l'intégralité du délai fourni par l'utilisateur, le client reçoit une erreur RESOURCE_EXHAUSTED.
Cette erreur est renvoyée si Spanner estime que le temps de traitement de la requête est trop long. L'erreur propage le contrôle de flux et Spanner réessaie la requête auprès du client, au lieu d'accumuler des tentatives en interne. Cela permet à Spanner d'éviter d'accumuler une consommation de ressources supplémentaire.