Gestion des erreurs avec DynamoDB

Cette section décrit les erreurs d’exécution et la façon de les traiter. Elle décrit également les messages d'erreur et les codes spécifiques d'Amazon DynamoDB. Pour obtenir la liste des erreurs courantes qui s'appliquent à tous les services AWS, consultez Gestion des accès.

Composants erreur

Quand votre programme envoie une demande, DynamoDB tente de la traiter. Si la demande aboutit, DynamoDB renvoie un code d'état HTTP de succès (200 OK), ainsi que les résultats de l'opération demandée.

Si la demande échoue, DynamoDB renvoie une erreur. Chaque erreur possède trois composants :

• Un code d’état HTTP (400, par exemple).

• Un nom d’exception (ResourceNotFoundException, par exemple).

• Un message d’erreur (Requested resource not found: Table: tablename not found, par exemple).

Les kits SDK AWS se chargent de propager les erreurs à votre application afin que vous puissiez prendre les mesures appropriées. Par exemple, dans un programme Java, vous pouvez écrire une logique try-catch de façon à gérer un ResourceNotFoundException.

Si vous n'utilisez pas de kit SDK AWS, vous devez analyser le contenu de la réponse de bas niveau de DynamoDB. Voici un exemple de réponse.

HTTP/1.1 400 Bad Request
x-amzn-RequestId: LDM6CJP8RMQ1FHKSC1RBVJFPNVV4KQNSO5AEMF66Q9ASUAAJG
Content-Type: application/x-amz-json-1.0
Content-Length: 240
Date: Thu, 15 Mar 2012 23:56:23 GMT

{"__type":"com.amazonaws.dynamodb.v20120810#ResourceNotFoundException",
"message":"Requested resource not found: Table: tablename not found"}

Erreurs transactionnelles

Pour plus d'informations sur les erreurs transactionnelles, veuillez consulter Gestion des conflits de transactions dans DynamoDB

Codes et messages d'erreur

Voici la liste des exceptions renvoyées par DynamoDB, regroupées par code d'état HTTP. Si OK to retry? a pour réponse Yes, vous pouvez soumettre à nouveau la même demande. Si OK to retry? a pour réponse No, vous devez résoudre le problème côté client avant de soumettre une nouvelle demande.

Code d'état HTTP 400

Un code d'état HTTP 400 indique un problème avec votre demande, tel qu'un échec d'authentification, l'absence de paramètres requis ou le dépassement du débit provisionné d'une table. Vous devez corriger le problème dans votre application avant de soumettre à nouveau la demande.

AccessDeniedException

Message : Accès refusé.

Le client n'a pas signé correctement la demande. Si vous utilisez un kit AWS SDK, les demandes sont signées automatiquement ; sinon, accédez au Processus de signature Signature Version 4 dans le Références générales AWS.

OK pour réessayer ? Non

ConditionalCheckFailedException

Message : Échec de la demande conditionnelle.

Vous avez spécifié une condition qui a été analysée comme false. Par exemple, il se peut que vous avez essayé d'effectuer une mise à jour conditionnelle sur un élément, mais que la valeur réelle de l'attribut ne corresponde pas à la valeur attendue de la condition.

OK pour réessayer ? Non

IncompleteSignatureException

Message : La signature de la demande n'est pas conforme aux normes AWS.

La signature de la demande ne comprenait pas tous les composants requis. Si vous utilisez un kit AWS SDK, les demandes sont signées automatiquement ; sinon, accédez au Processus de signature Signature Version 4 dans le Références générales AWS.

OK pour réessayer ? Non

ItemCollectionSizeLimitExceededException

Message : Dépassement de taille de la collection.

Pour une table avec un index secondaire local, un groupe d'éléments avec la même valeur de clé de partition a dépassé la limite de taille maximum de 10 Go. Pour plus d'informations sur les collections d'éléments, consultez Collections d'articles dans les index secondaires locaux.

OK pour réessayer ? Oui

LimitExceededException

Message : Beaucoup trop d'opérations pour un abonné donné.

Il y a beaucoup trop d'opérations de contrôle simultanées. Le nombre cumulé de tables et d'index à l'état CREATING, DELETING ou UPDATING ne peut pas dépasser 500.

OK pour réessayer ? Oui

MissingAuthenticationTokenException

Message : La demande doit comporter un ID de clé d'accès AWS valide (inscrit).

La demande n'incluait pas l'en-tête d'autorisation obligatoire ou n'était pas correctement formée. veuillez consulter API de bas niveau de DynamoDB.

OK pour réessayer ? Non

ProvisionedThroughputExceededException

Message : Vous avez dépassé le débit approvisionné autorisé maximal pour une table ou pour un ou plusieurs index secondaires globaux. Pour consulter les indicateurs de performance relatifs au débit provisionné par rapport au débit consommé, ouvrez la console Amazon. CloudWatch

Exemple : votre taux de demandes est trop élevé. Les kits SDK AWS pour DynamoDB relancent automatiquement les demandes qui reçoivent cette exception. Votre demande finit par aboutir, à moins que la file d'attente des nouvelles tentatives soit trop grande pour être terminée. Réduisez la fréquence des demandes avec Nouvelles tentatives après erreur et backoff exponentiel.

OK pour réessayer ? Oui

RequestLimitExceeded

Message : Throughput exceeds the current throughput limit for your account (le débit dépasse la limite de débit actuelle de votre compte). Pour demander une augmentation de la limite, contactez le Support AWS à l'adresse https://aws.amazon.com/support.

Exemple : le taux de requêtes à la demande dépasse le débit autorisé du compte et la table ne peut pas être agrandie davantage.

OK pour réessayer ? Oui

ResourceInUseException

Message : La ressource que vous essayez de modifier est en cours d'utilisation.

Exemple : vous avez essayé de recréer une table existante ou de supprimer une table dont l'état est CREATING.

OK pour réessayer ? Non

ResourceNotFoundException

Message : La ressource demandée est introuvable.

Exemple : la table demandée n'existe pas ou se trouve trop tôt dans l'état CREATING.

OK pour réessayer ? Non

ThrottlingException

Message : Le taux de demandes dépasse le débit autorisé.

Cette exception est renvoyée sous forme de AmazonServiceException réponse avec un code d'état THROTTLING_EXCEPTION. Cette exception peut être renvoyée si vous effectuez des opérations d'API de plan de contrôle trop rapidement.

Pour les tables utilisant le mode à la demande, cette exception peut être renvoyée pour toute opération d'API de plan de données si votre taux de demandes est trop élevé. Pour en savoir plus sur la mise à l'échelle à la demande, consultez Trafic de pointe et propriétés de scalabilité

OK pour réessayer ? Oui

UnrecognizedClientException

Message : L'ID de clé d'accès ou le jeton de sécurité n'est pas valide.

La signature de la demande est incorrecte. La cause la plus probable est une clé secrète ou un ID de clé d'accès AWS non valides.

OK pour réessayer ? Oui

ValidationException

Message : variable selon les erreurs spécifiques rencontrées

Cette erreur peut se produire pour différentes raisons, telles qu'un paramètre obligatoire absent, une valeur en dehors des limites ou une incompatibilité des données. Le message d'erreur contient des détails sur la partie spécifique de la demande qui a provoqué l'erreur.

OK pour réessayer ? Non

Code d’état HTTP 5xx

Un code d’état HTTP 5xx indique un problème qui doit être résolu par AWS. Il peut s'agir d'une erreur temporaire, auquel cas vous pouvez retenter votre demande jusqu'à ce qu'elle aboutisse. Sinon, accédez à l'AWS Service Health Dashboard pour voir si le service rencontre des problèmes opérationnels.

Pour plus d'informations, consultez l'article Comment résoudre les erreurs HTTP 5xx dans Amazon DynamoDB ?

InternalServerError (HTTP 500)

DynamoDB n'a pas pu traiter votre demande.

OK pour réessayer ? Oui

Note

Vous pouvez rencontrer des erreurs de serveur internes lorsque vous travaillez avec des éléments. Celles-ci sont attendues pendant la durée de vie d'une table. Toute demande en échec peut être relancée immédiatement.

Lorsque vous recevez un code d'état 500 lors d'une opération d'écriture, l'opération peut avoir réussi ou échoué. Si l'opération d'écriture est une demande TransactWriteItem, il convient de réessayer l'opération. Si l'opération d'écriture est une demande d'écriture à un seul élément, telle que PutItem, UpdateItem, ou DeleteItem, votre application doit alors lire l'état de l'élément avant de réessayer l'opération et/ou utiliser Expressions de condition pour s'assurer que l'élément reste dans un état correct après une nouvelle tentative, que l'opération précédente ait réussi ou échoué. Si l'idempotence est une exigence pour l'opération d'écriture, veuillez utiliser TransactWriteItem, qui prend en charge les demandes idempotentes en spécifiant automatiquement un ClientRequestToken pour désambiguïser plusieurs tentatives d'exécution de la même action.

ServiceUnavailable (HTTP 503)

DynamoDB est actuellement indisponible. (Il doit s'agir d'un état temporaire.)

OK pour réessayer ? Oui

Gestion des erreurs dans votre application

Pour que votre application fonctionne correctement, vous devez ajouter une logique destinée à récupérer les erreurs et à y répondre. Les approches classiques incluent l’utilisation de blocs try-catch ou d’instructions if-then.

Les kits SDK AWS effectuent leurs propres tentatives et contrôles d'erreur. Si vous rencontrez une erreur lors de l'utilisation de l'un des kits SDK AWS, le code et la description de l'erreur peuvent vous aider à la résoudre.

Vous devez également voir un Request ID dans la réponse. Le Request ID peut être utile si vous devez utiliser AWS Support pour diagnostiquer un problème.

Nouvelles tentatives après erreur et backoff exponentiel

Un grand nombre de composants d'un réseau, tels que serveurs DNS, commutateurs, équilibreurs de charge ou autres, peuvent générer des erreurs à n'importe quel moment de la vie d'une requête donnée. La technique habituelle pour traiter ces réponses erronées dans un environnement réseau consiste à implémenter les nouvelles tentatives dans l'application cliente. Cette technique augmente la fiabilité de l'application.

Chaque kit SDK AWS implémente automatiquement la logique de nouvelle tentative. Vous pouvez modifier les paramètres de nouvelle tentative en fonction de vos besoins. Par exemple, imaginons une application Java nécessitant une politique d'interruption immédiate, sans autorisation de nouvelle tentative en cas d'erreur. Avec le AWS SDK for Java, vous pouvez utiliser la classe ClientConfiguration et fournir une valeur maxErrorRetry égale à 0 pour désactiver les nouvelles tentatives. Pour plus d'informations, consultez la documentation du kit SDK AWS correspondant à votre langage de programmation.

Si vous n'utilisez pas un kit SDK AWS, vous devez relancer les demandes d'origine qui reçoivent des erreurs de serveur (5xx). Cependant, les erreurs client (4xx, autres qu'une exception ThrottlingException ou ProvisionedThroughputExceededException) indiquent que vous avez besoin de réviser la demande elle-même pour résoudre le problème avant de recommencer.

Outre les nouvelles tentatives simples, chaque kit SDK AWS implémente un algorithme de backoff exponentiel pour un meilleur contrôle des flux. Le concept sous-jacent vise à utiliser des temps d'attente progressivement plus longs entre les tentatives en cas de réponses d'erreur consécutives. Par exemple, jusqu'à 50 millisecondes avant la première nouvelle tentative, jusqu'à 100 millisecondes avant la deuxième, jusqu'à 200 millisecondes avant la troisième, et ainsi de suite. Cependant, après une minute, si la demande a échoué, le problème peut être que la taille de la demande entraîne un dépassement du débit provisionné, et ne pas être lié au taux de demandes. Définir le nombre maximal de nouvelles tentatives pour qu'elles s'arrêtent au bout d'une minute environ. Si la demande n'aboutit pas, examinez vos options de débit approvisionné.

Note

Les kits SDK AWS implémentent une logique de nouvelle tentative et un backoff exponentiel automatiques.

La plupart des algorithmes de backoff exponentiel utilisent l'instabilité (retard aléatoire) pour éviter les conflits successifs. Comme vous ne cherchez pas à éviter de tels conflits dans ces cas-là, vous n'avez pas besoin d'utiliser ce nombre aléatoire. Cependant, si vous utilisez les clients simultanés, l'instabilité peut aider à ce que vos demandes réussissent plus rapidement. Pour plus d'informations, consultez le billet de blog sur Exponential backoff and jitter.

Opérations par lot et gestion des erreurs

L'API de bas niveau DynamoDB prend en charge les opérations par lot pour les lectures et les écritures. BatchGetItem lit les éléments d'une ou de plusieurs tables, et BatchWriteItem insère ou supprime des éléments dans une ou plusieurs tables. Ces opérations par lot sont implémentées sous la forme d'encapsuleurs autour des opérations DynamoDB autres que par lot. En d'autres termes, BatchGetItem appelle GetItem une fois pour chaque élément du lot. De même, BatchWriteItem appelle DeleteItem ou PutItem, le cas échéant, pour chaque élément du lot.

Une opération par lot peut supporter la défaillance de requêtes individuelles dans le lot. Par exemple, imaginons une demande BatchGetItem de lecture de cinq éléments. Même si certaines demandes GetItem sous-jacentes échouent, il ne s'ensuit pas que l'ensemble de l'opération BatchGetItem échoue. Cependant, si les cinq opérations de lecture échouent, alors BatchGetItem échoue dans son intégralité.

Les opérations par lot renvoient des informations sur les demandes individuelles qui échouent pour vous permettre de diagnostiquer le problème et de réessayer l'opération. Pour BatchGetItem, les tables et les clés primaires en question sont retournées dans la valeur UnprocessedKeys de la réponse. Pour BatchWriteItem, les informations similaires sont retournées dans UnprocessedItems.

La cause la plus probable d'un échec en lecture ou en écriture est la limitation. Pour BatchGetItem, une ou plusieurs tables de la demande par lot n'ont pas une capacité en lecture suffisamment provisionnée pour prendre en charge l'opération. Pour BatchWriteItem, une ou plusieurs des tables n'ont pas une capacité en écriture suffisamment provisionnée.

Si DynamoDB renvoie des éléments non traités, vous devez relancer l'opération par lot sur ces éléments. Cependant, nous vous recommandons vivement d'utiliser un algorithme d'interruption exponentielle. Si vous recommencez immédiatement l'opération par lot, les demandes en lecture ou en écriture sous-jacentes peuvent continuer à échouer en raison de la limitation sur les tables individuelles. Si vous retardez l'opération par lot à l'aide d'une interruption exponentielle, il est très vraisemblable que les demandes du lot réussiront.