Gestione degli errori con DynamoDB

Questa sezione descrive gli errori di runtime e come gestirli. Descrive inoltre i messaggi e codici di errore specifici di Amazon DynamoDB. Per un elenco degli errori comuni che si applicano a tutti i servizi AWS, consulta Gestione degli accessi

Componenti degli errori

Quando il tuo programma invia una richiesta, DynamoDB prova a elaborarla. Se la richiesta ha esito positivo, DynamoDB restituisce un codice di stato HTTP di operazione riuscita (200 OK), insieme ai risultati dell'operazione richiesta.

Se la richiesta ha esito negativo, DynamoDB restituisce un errore. Ogni errore comprende tre componenti:

• Un codice di stato HTTP (ad esempio, 400).

• Un nome di eccezione (ad esempio, ResourceNotFoundException).

• Un messaggio di errore (ad esempio Requested resource not found: Table: tablename not found).

Gli SDK AWS si occupano della propagazione degli errori alla tua applicazione per consentirti di adottare le misure appropriate. Ad esempio, in un programma Java puoi scrivere logica try-catch per gestire un errore ResourceNotFoundException.

Se non stai utilizzando un SDK AWS, devi analizzare il contenuto della risposta di basso livello da DynamoDB. Di seguito è riportato un esempio di tale risposta:

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"}

Errori transazionali

Per informazioni sugli errori transazionali, consulta Gestione dei conflitti nelle transazioni in DynamoDB

Messaggi e codici di errore

Di seguito è riportato un elenco di eccezioni restituite da DynamoDB, raggruppate in base al codice di stato HTTP. Se OK to retry? (OK riprovare?) è Yes (Sì), puoi inviare nuovamente la stessa richiesta. Se OK to retry? (OK riprovare?) è No, è necessario risolvere il problema sul lato client prima di inviare una nuova richiesta.

Codice di stato HTTP 400

Un codice di stato HTTP 400 indica un problema della richiesta, ad esempio un errore di autenticazione, l'assenza di parametri obbligatori o il superamento del throughput assegnato di una tabella. È necessario risolvere il problema nella tua applicazione prima di inviare nuovamente la richiesta.

AccessDeniedException

Messaggio: Access denied.

Il client non ha firmato correttamente la richiesta. Se utilizzi un SDK AWS, le richieste vengono firmate automaticamente; in caso contrario, consulta Processo di firma in Signature version 4 in Riferimenti generali di AWS.

OK riprovare? No

ConditionalCheckFailedException

Messaggio: The conditional request failed.

Hai specificato una condizione che ha restituito il valore false. Ad esempio, è possibile che si sia provato un aggiornamento condizionale su un elemento, ma il valore effettivo dell’attributo non corrispondesse al valore previsto nella condizione.

OK riprovare? No

IncompleteSignatureException

Messaggio: The request signature does not conform to AWS standards.

La firma della richiesta non include tutti i componenti obbligatori. Se utilizzi un SDK AWS, le richieste vengono firmate automaticamente; in caso contrario, consulta Processo di firma in Signature Version 4 in Riferimenti generali di AWS.

OK riprovare? No

ItemCollectionSizeLimitExceededException

Messaggio: Collection size exceeded.

Per una tabella con un indice secondario locale, un gruppo di elementi con lo stesso valore di chiave di partizione ha superato il limite massimo di dimensione pari a 10 GB. Per ulteriori informazioni sulle raccolte di item, consulta Raccolte di elementi negli indici secondari locali.

OK riprovare? Sì

LimitExceededException

Messaggio: Too many operations for a given subscriber.

Ci sono troppe operazioni di piano di controllo simultanee. Il numero complessivo di tabelle e indici in stato CREATING, DELETING o UPDATING non può superare 500.

OK riprovare? Sì

MissingAuthenticationTokenException

Messaggio: Request must contain a valid (registered) AWS Access Key ID.

La richiesta non include l'intestazione di autorizzazione richiesta o il formato non è corretto. Consultare API DynamoDB di basso livello.

OK riprovare? No

ProvisionedThroughputExceededException

Messaggio: You exceeded your maximum allowed provisioned throughput for a table or for one or more global secondary indexes. To view performance metrics for provisioned throughput vs. consumed throughput, open the Amazon CloudWatch console.

L’errore include un elenco di campi ThrottlingReason che forniscono un contesto specifico sul motivo per cui si è verificata la limitazione (della larghezza di banda della rete), in base al formato ResourceType+OperationType+LimitType (ad esempio, TableReadProvisionedThroughputExceeded) e all’ARN della risorsa interessata. Ciò consente di identificare quale risorsa è sottoposta a limitazione (della larghezza di banda della rete) (tabella o indice), quale tipo di operazione ha attivato la limitazione (lettura o scrittura) e il limite specifico che è stato superato (in questo caso: capacità allocata). Per ulteriori informazioni sulla diagnosi e la risoluzione dei problemi relativi alla limitazione (della larghezza di banda della rete), consulta Diagnosi della limitazione (della larghezza di banda della rete).

Esempio: la frequenza di richieste è troppo elevata. Gli SDK AWS per DynamoDB riprovano automaticamente le richieste che ricevono questa eccezione. La richiesta ha infine esito positivo, a meno che la coda dei tentativi ripetuti sia troppo estesa per terminare. Riduci la frequenza delle richieste utilizzando Ripetizione dei tentativi in caso di errore e backoff esponenziale.

OK riprovare? Sì

ReplicatedWriteConflictException

Messaggio: One or more items in this request are being modified by a request in another Region.

Esempio: è stata richiesta un’operazione di scrittura per un elemento in una tabella globale a elevata consistenza multi-Regione (MRSC) che è attualmente in fase di modifica da una richiesta in un’altra Regione.

OK riprovare? Sì

RequestLimitExceeded

Messaggio: Throughput exceeds the current throughput limit for your account. To request a limit increase, contact AWS Support at https://aws.amazon.com/support (La velocità di trasmissione effettiva supera il limite corrente per l'account. Per richiedere un aumento del limite, contatta il supporto all'indirizzo https://aws.amazon.com/support.).

L’errore include un elenco di campi ThrottlingReason che forniscono un contesto specifico sul motivo per cui si è verificata la limitazione (della larghezza di banda della rete), in base al formato ResourceType+OperationType+LimitType (ad esempio, TableWriteAccountLimitExceeded o IndexReadAccountLimitExceeded) e all’ARN della risorsa interessata. Ciò consente di identificare quale risorsa viene sottoposta a limitazione (della larghezza di banda della rete) (tabella o indice), quale tipo di operazione ha attivato la limitazione (lettura o scrittura) e se sono state superate le quote di servizio a livello di account. Per ulteriori informazioni sulla diagnosi e la risoluzione dei problemi relativi alla limitazione (della larghezza di banda della rete), consulta Diagnosi della limitazione (della larghezza di banda della rete).

Esempio: la frequenza delle richieste on demand supera la velocità di trasmissione effettiva dell'account consentita e alla tabella non può essere applicato un ulteriore dimensionamento.

OK riprovare? Sì

ResourceInUseException

Messaggio: The resource which you are attempting to change is in use.

Esempio: hai provato a ricreare una tabella esistente o a eliminare una tabella attualmente in stato CREATING.

OK riprovare? No

ResourceNotFoundException

Messaggio: Requested resource not found.

Esempio: la tabella richiesta non esiste o si trova nella prima fase dello stato CREATING.

OK riprovare? No

ThrottlingException

Messaggio: Rate of requests exceeds the allowed throughput.

Questa eccezione viene restituita come risposta AmazonServiceException con un codice di stato THROTTLING_EXCEPTION. Questa eccezione potrebbe essere restituita se si eseguono operazioni API del piano di controllo troppo rapidamente.

Per le tabelle che utilizzano la modalità on demand, questa eccezione potrebbe essere restituita per qualsiasi operazione API del piano dati se la frequenza di richiesta è troppo alta. Per ulteriori informazioni sul dimensionamento on demand, consulta Throughput e proprietà di dimensionamento.

L’errore include un elenco di campi ThrottlingReason che forniscono un contesto specifico sul motivo per cui si è verificata la limitazione (della larghezza di banda della rete), in base al formato ResourceType+OperationType+LimitType (ad esempio, TableReadKeyRangeThroughputExceeded o IndexWriteMaxOnDemandThroughputExceeded) e all’ARN della risorsa interessata. Queste informazioni consentono di identificare quale risorsa viene sottoposta a limitazione (della larghezza di banda della rete) (tabella o indice), quale tipo di operazione ha attivato la limitazione (lettura o scrittura) e il limite specifico che è stato superato (limiti di partizione o throughput massimo on demand). Per ulteriori informazioni sulla diagnosi e la risoluzione dei problemi relativi alla limitazione (della larghezza di banda della rete), consulta Diagnosi della limitazione (della larghezza di banda della rete).

OK riprovare? Sì

UnrecognizedClientException

Messaggio: The Access Key ID or security token is invalid.

La firma della richiesta non è corretta. La causa più probabile è un ID chiave di accesso AWS o una chiave segreta non valida.

OK riprovare? Sì

ValidationException

Messaggio: variabile, in base all'errore o agli errori specifici rilevati

Questo errore può verificarsi per vari motivi, ad esempio per un parametro obbligatorio mancante, un valore non compreso nell'intervallo valido o tipi di dati non corrispondenti. Il messaggio di errore contiene dettagli sulla parte specifica della richiesta che ha causato l'errore.

OK riprovare? No

Codice di stato HTTP 5xx

Un codice di stato HTTP 5xx indica un problema che deve essere risolto da AWS. Potrebbe trattarsi di un errore temporaneo, nel qual caso puoi riprovare la richiesta finché non riesce. In caso contrario, accedi al AWS Service Health Dashboard per verificare se ci sono problemi operativi relativi al servizio.

Per ulteriori informazioni, consulta Come risolvere gli errori HTTP 5xx in Amazon DynamoDB?

InternalServerError (HTTP 500)

DynamoDB non è riuscito a elaborare la richiesta.

OK riprovare? Sì

Nota

Puoi rilevare errori interni del server durante la gestione degli item. Sono previsti nel corso della durata di una tabella. Le richieste non riuscite possono essere riprovate immediatamente.

Quando ricevi un codice di stato 500 in un'operazione di scrittura, l'operazione potrebbe essere stata eseguita correttamente o non essere riuscita. Se l'operazione di scrittura è una richiesta TransactWriteItem, è possibile riprovare a eseguire l'operazione. Se l'operazione di scrittura è una richiesta di scrittura con un elemento singolo, ad esempio PutItem, UpdateItem o DeleteItem, la tua applicazione dovrebbe leggere lo stato dell'elemento prima di riprovare l'operazione e/o utilizzare Esempio di CLI di espressione condizionale in DynamoDB per garantire che l'elemento rimanga in uno stato corretto dopo aver riprovato, indipendentemente dal fatto che l'operazione precedente abbia avuto esito positivo o non sia riuscita. Se l'idempotenza è un requisito per l'operazione di scrittura, utilizza TransactWriteItem, che supporta le richieste idempotenti specificando automaticamente un ClientRequestToken per disambiguare più tentativi di eseguire la stessa azione.

ServiceUnavailable (HTTP 503)

DynamoDB al momento non è disponibile. Dovrebbe trattarsi di uno stato temporaneo.

OK riprovare? Sì

Gestione degli errori nell'applicazione

Per il buon funzionamento dell'applicazione devi aggiungere logica che intercetti gli errori e risponda in modo adeguato. Gli approcci tipici includono l'utilizzo di blocchi try-catch o di istruzioni if-then.

Gli SDK AWS eseguono le proprie ripetizioni di tentativi e le proprie verifiche degli errori. Se rilevi un errore durante l'utilizzo di uno degli SDK AWS, il codice e la descrizione dell'errore possono aiutarti a risolverlo.

Dovresti anche vedere un Request ID nella risposta. L'Request ID può essere utile se devi collaborare con AWS Support per diagnosticare un problema.

Ripetizione dei tentativi in caso di errore e backoff esponenziale

Numerosi componenti di una rete, ad esempio server DNS, switch, sistemi di bilanciamento del carico e altri, possono generare errori in qualsiasi fase del ciclo di vita di una richiesta specifica. La tecnica che viene generalmente utilizzata per gestire queste risposte di errore in un ambiente di rete consiste nell'implementare nuovi tentativi nell'applicazione client. Questa tecnica aumenta l'affidabilità dell'applicazione.

Ogni SDK AWS implementa automaticamente la logica di ripetizione dei tentativi. Puoi modificare i parametri delle ripetizioni in base alle tue esigenze. Considera ad esempio un'applicazione Java che richiede una strategia fail-fast, senza tentativi ripetuti in caso di errore. Con l'AWS SDK per Java potresti utilizzare la classe ClientConfiguration e specificare un valore maxErrorRetry uguale a 0 per disattivare i tentativi. Per ulteriori informazioni, consulta la documentazione sugli SDK AWS relativa al tuo linguaggio di programmazione.

Se non utilizzi un SDK AWS, dovresti riprovare le richieste originali che ricevono errori del server (5xx). Tuttavia, gli errori del client (4xx, tranne ThrottlingException o ProvisionedThroughputExceededException) indicano che devi modificare la richiesta per correggere il problema prima di riprovare. Per consigli dettagliati per affrontare scenari di limitazione (della larghezza di banda della rete) specifici, consulta la sezione Risoluzione dei problemi relativi alla limitazione (della larghezza di banda della rete) in DynamoDB.

Oltre a semplici tentativi, ogni SDK AWS implementa l'algoritmo di backoff esponenziale per migliorare il controllo del flusso. Il concetto che sottende al backoff esponenziale è di utilizzare attese progressivamente più lunghe tra i tentativi per le risposte di errore consecutive. Ad esempio, fino a 50 millisecondi prima del primo nuovo tentativo, fino a 100 millisecondi prima del secondo, fino a 200 millisecondi prima del terzo e così via. Tuttavia, dopo un minuto, se la richiesta non è riuscita, il problema potrebbe essere dovuto al fatto che la dimensione della richiesta ha superato il throughput assegnato e non essere causato dalla frequenza della richiesta. Imposta l'arresto del numero massimo di tentativi a circa un minuto. If the request is not successful, investigate your provisioned throughput options.

Nota

Gli SDK AWS implementano automaticamente la logica di ripetizione dei tentativi e il backoff esponenziale.

La maggior parte degli algoritmi di backoff esponenziale utilizza il jitter (ritardo randomizzato) per evitare collisioni successive. Poiché in questi casi non stai provando a evitare tali collisioni, non è necessario utilizzare questo numero casuale. Tuttavia, se utilizzi client simultanei, il jitter può aiutare a completare più velocemente le richieste. Per ulteriori informazioni, consulta il post del blog relativo al jitter e al backoff esponenziale.

Operazioni in batch e gestione degli errori

L'API di basso livello di DynamoDB supporta operazioni in batch per le letture e le scritture. BatchGetItem legge elementi da una o più tabelle e BatchWriteItem inserisce o elimina gli elementi in una o più tabelle. Queste operazioni in batch vengono implementate come wrapper di altre operazioni DynamoDB non batch. In altre parole, BatchGetItem richiama GetItem una volta per ogni item nel batch. Analogamente, BatchWriteItem richiama DeleteItem o PutItem, in base al caso, per ogni item nel batch.

Un'operazione batch può tollerare l'errore di singole richieste nel batch. Considera ad esempio una richiesta BatchGetItem per la lettura di cinque item. La mancata elaborazione di alcune richieste GetItem sottostanti non comporta l'errore dell'intera operazione BatchGetItem. Tuttavia, se tutte e cinque le operazioni non riescono, l'intero BatchGetItem non riesce.

Le operazioni batch restituiscono informazioni sulle singole richieste non riuscite, in modo che tu possa diagnosticare il problema e riprovare l'operazione. Per BatchGetItem, le tabelle e le chiavi primarie in questione vengono restituite nel valore UnprocessedKeys della risposta. Per BatchWriteItem, informazioni simili vengono restituite in UnprocessedItems.

La causa più probabile della mancata riuscita di una lettura o scrittura è il throttling. Per BatchGetItem, una o più tabelle nella richiesta batch non dispongono di capacità di lettura assegnata sufficiente a supportare l'operazione. Per BatchWriteItem, una o più tabelle nella richiesta batch non dispongono di capacità di scrittura assegnata sufficiente.

Se DynamoDB restituisce elementi non elaborati, dovresti riprovare l'operazione in batch su quegli elementi. Tuttavia, è fortemente consigliabile utilizzare un algoritmo di backoff esponenziale. Se riprovi l'operazione batch immediatamente, le richieste di lettura o scrittura sottostanti possono ancora non riuscire a causa del throttling sulle singole tabelle. Se ritardi le operazioni in batch utilizzando il backoff esponenziale, le singole richieste nel batch avranno una probabilità di riuscita molto maggiore.