Postconditions: what we check

• send · aws-dynamodb-service-error

  error
  WhenAny AWS service error or network failure: table does not exist (ResourceNotFoundException), throughput exceeded (ProvisionedThroughputExceededException), conditional expression failed (ConditionalCheckFailedException), transaction cancelled (TransactionCanceledException), concurrent transaction conflict (TransactionConflictException), account rate limit exceeded (RequestLimitExceeded), malformed parameters (ValidationException), permission denied (AccessDeniedException), service unavailable (ServiceUnavailable), or any network-level failure (DNS, timeout, connection refused)
  ThrowsDynamoDBServiceException subclass with error.name set to the specific error code (e.g., "ResourceNotFoundException", "ProvisionedThroughputExceededException", "ConditionalCheckFailedException", "TransactionCanceledException"). For network errors, throws a generic Error or SdkClientError.
  Required handlingCaller MUST wrap client.send() in try-catch. All DynamoDB operations can fail due to network issues, throughput limits, conditional check failures, or AWS service outages. Unhandled rejections crash API routes, Lambda handlers, and background workers. Minimum handling: try { await dynamoClient.send(new PutItemCommand({ TableName, Item })); } catch (error) { if (error instanceof DynamoDBServiceException) { if (error.name === 'ConditionalCheckFailedException') { // Optimistic lock conflict — handle as business logic } else if (error.name === 'ProvisionedThroughputExceededException') { // Throttled — implement exponential backoff with jitter } else { console.error(`DynamoDB error [${error.name}]: ${error.message}`); } } else { console.error('Network error:', error); } throw error; } For transactional writes, inspect CancellationReasons: } catch (error) { if (error instanceof TransactionCanceledException) { for (const reason of error.CancellationReasons ?? []) { if (reason.Code === 'ConditionalCheckFailed') { throw new OptimisticLockError(reason.Message); } } } throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2][3][4]
• BatchWriteItemCommand · batch-write-unprocessed-items-not-checked

  error
  WhenBatchWriteItemCommand succeeds (no throw) but response.UnprocessedItems is non-empty — some items were NOT written due to throughput limits or internal AWS processing failures. Caller does not check response.UnprocessedItems.
  Required handlingCaller MUST check response.UnprocessedItems after every BatchWriteItem call and retry with exponential backoff. AWS strongly recommends exponential backoff.
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[5][6]
• BatchGetItemCommand · batch-get-unprocessed-keys-not-checked

  error
  WhenBatchGetItemCommand succeeds (no throw) but response.UnprocessedKeys is non-empty — some items could not be read due to throughput limits or 16 MB response size limit. Caller does not check response.UnprocessedKeys.
  Required handlingCaller MUST check response.UnprocessedKeys and retry in a loop until empty, using exponential backoff between retries.
  costhighin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[7][6]
• TransactWriteItemsCommand · transact-write-cancellation-reasons-not-inspected

  error
  WhenTransactWriteItemsCommand throws TransactionCanceledException and caller catches it but does not inspect CancellationReasons array to distinguish ConditionalCheckFailed (business conflict, NOT retryable) from ProvisionedThroughputExceeded or TransactionConflict (infrastructure, retryable).
  Required handlingCaller MUST catch TransactionCanceledException and inspect CancellationReasons to distinguish ConditionalCheckFailed (not retryable) from TransactionConflict and ProvisionedThroughputExceeded (retryable with exponential backoff).
  costhighin prodsilent failureusers seelost transactionvisibilitysilent
  Sources[8][9]
• TransactWriteItemsCommand · transact-write-in-progress-exception

  warning
  WhenCaller retries TransactWriteItemsCommand before the previous attempt completes, using the same ClientRequestToken, causing TransactionInProgressException.
  Required handlingUse unique ClientRequestToken per logical transaction. Do not retry with the same token within 10 minutes unless the payload is identical. Implement application-level retries only for TransactionCanceledException.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[8]
• ExecuteStatementCommand · execute-statement-duplicate-item

  error
  WhenPartiQL INSERT statement targets a primary key that already exists in the table. DuplicateItemException is thrown. Caller has no try-catch or catches generically without checking for DuplicateItemException specifically.
  Required handlingCallers using PartiQL INSERT MUST catch DuplicateItemException specifically and return a user-friendly error rather than propagating an unhandled exception.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10][11]
• ExecuteTransactionCommand · execute-transaction-cancellation-reasons-not-inspected

  error
  WhenExecuteTransactionCommand throws TransactionCanceledException and caller catches it but does not inspect CancellationReasons array to distinguish ConditionalCheckFailed (business conflict, NOT retryable) from ProvisionedThroughputExceeded or TransactionConflict (infrastructure failures, retryable).
  Required handlingCaller MUST catch TransactionCanceledException and inspect CancellationReasons to distinguish ConditionalCheckFailed (not retryable — business conflict) from TransactionConflict and ProvisionedThroughputExceeded (retryable).
  costhighin prodsilent failureusers seelost transactionvisibilitysilent
  Sources[12][9]
• ExecuteTransactionCommand · execute-transaction-idempotent-parameter-mismatch

  error
  WhenCaller retries ExecuteTransactionCommand with the same ClientRequestToken but different PartiQL statements, causing IdempotentParameterMismatchException. This occurs when retry logic reuses tokens without matching the original payload.
  Required handlingGenerate a unique ClientRequestToken per logical transaction attempt. Never reuse a token with a different statement set. Use a UUID v4 per call. Do not retry with the same token if the error is IdempotentParameterMismatchException.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[12]
• BatchExecuteStatementCommand · batch-execute-statement-response-errors-not-checked

  error
  WhenBatchExecuteStatementCommand succeeds (no throw) but one or more entries in response.Responses have a non-null Error field indicating that statement failed. Caller does not iterate response.Responses and check each entry's Error field.
  Required handlingCaller MUST iterate response.Responses after every BatchExecuteStatement call and check each entry's Error field. For throughput errors (ProvisionedThroughputExceeded, ThrottlingError), retry the failed statements with exponential backoff. For DuplicateItem and ConditionalCheckFailed, treat as business-logic errors (not retryable).
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[13][14]
• waitUntilTableExists · aws-dynamodb-wait-until-table-exists-no-try-catch

  error
  WhenCall to waitUntilTableExists (or any waitUntil* waiter from this SDK) is awaited without a surrounding try-catch. The waiter rejects with TimeoutError (error.name === "TimeoutError") when DescribeTable acceptor never resolves to ACTIVE within WaiterConfiguration.maxWaitTime, or with AbortError (error.name === "AbortError") when WaiterConfiguration.abortSignal fires.
  Required handlingWrap waitUntilTableExists (and any waitUntil* sibling) in try-catch. Inspect error.name to distinguish TimeoutError (retry with longer maxWaitTime, or alert on stuck provisioning) from AbortError (graceful shutdown — propagate cancellation, do not retry) from any other rejection (likely DynamoDBServiceException from the underlying DescribeTable call). Minimum handling: try { await waitUntilTableExists( { client: dynamoClient, maxWaitTime: 60 }, { TableName: 'orders' } ); } catch (error) { if (error.name === 'TimeoutError') { throw new ProvisioningTimeoutError('Table did not become ACTIVE within 60s'); } if (error.name === 'AbortError') { // Graceful cancellation — propagate to caller, do not treat as failure throw error; } throw error; } For workflows that legitimately retry the wait (e.g. tenant provisioning with longer maxWaitTime on TimeoutError), implement bounded retry with exponential backoff. Never swallow TimeoutError silently — that hides the SaaS owner's only signal that table provisioning is stuck.
  costmediumin proddelayed failureusers seeservice unavailablevisibilityvisible
  Sources[15][16][17]
• waitUntilTableExists · aws-dynamodb-wait-until-abort-not-distinguished

  warning
  WhenCaller wraps waitUntilTableExists (or any waitUntil* waiter) in try-catch but treats AbortError the same as TimeoutError or DynamoDBServiceException — does not check error.name === "AbortError" and does not propagate cancellation distinctly from failure.
  Required handlingWhen using waitUntil* with an abortSignal, branch on error.name === "AbortError" in the catch and propagate cancellation distinctly (re-throw, return a cancellation result, or set a 499 status). Never retry an AbortError — the caller explicitly cancelled. Use a separate branch for TimeoutError (may retry with longer maxWaitTime) and a third branch for everything else (typically DynamoDBServiceException from the underlying DescribeTable / DescribeExport / DescribeImport / DescribeContributorInsights / DescribeKinesisStreamingDestination acceptor, surfaced as a generic Error wrapping the service exception). Recommended pattern: const abortSignal = AbortSignal.timeout(60_000); try { await waitUntilTableExists( { client: dynamoClient, maxWaitTime: 60, abortSignal }, { TableName: 'orders' } ); } catch (error) { if (error.name === 'AbortError') { // Caller cancelled (signal fired) — propagate cancellation throw new CancelledError('Wait cancelled by caller'); } if (error.name === 'TimeoutError') { // Bounded retry, then alert throw new ProvisioningStuckError(...); } // Underlying DescribeTable failed — service error throw error; }
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[17][18][19]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.