2- Provisioned throughput exceeded - Amazon DynamoDB
Provisioned throughput exceeded mitigation measuresCommon diagnosis and monitoringResolution proceduresAdditional resources

2- Provisioned throughput exceeded

Provisioned capacity throttling occurs when your application's consumption rate exceeds the read or write capacity units (RCUs/WCUs) configured for your tables or global secondary indexes. While DynamoDB provides burst capacity to handle occasional traffic spikes, sustained requests beyond your provisioned limits result in throttling. When this happens, DynamoDB returns a ProvisionedThroughputExceeded throttling reason type in the throttling exception. The reason identifies whether the issue is with read or write operations and whether it affects the base table or a global secondary index.

Throttling can occur regardless of whether Auto Scaling is enabled. Auto Scaling adapts to increases in consumption, but it does not respond instantly and it is constrained by the maximum capacity limits you configure. This means throttling can still occur during sudden traffic spikes or when consumption exceeds your maximum Auto Scaling limits.

Provisioned throughput exceeded mitigation measures

This section provides resolution guidance for provisioned capacity throttling scenarios. Before using this guide, ensure you have identified the specific throttling reason from your application's exception handling, and determined the Amazon Resource Name (ARN) of the affected resource. For information on retrieving throttling reasons and identifying throttled resources, see DynamoDB throttling diagnosis framework.

Before diving into specific throttling scenarios, first consider if the throttling is actually a problem that needs resolution:

  • Occasional throttling is normal and expected in well-optimized DynamoDB applications. Throttling simply means you're consuming 100% of what you've provisioned. If your application handles throttling gracefully with retries and your overall performance meets requirements, the throttling may not require immediate action.

  • However, if throttling is causing unacceptable client-side latency, degrading user experience, or preventing critical operations from completing in a timely manner, then proceed with the mitigation options below.

When you need to address throttling issues, first determine if your throttling is caused by:

  • Temporary traffic spikes: Short-duration increases in traffic that exceed your provisioned capacity but aren't sustained. These require different strategies than continuous high traffic.

  • Continuous high traffic: Sustained workloads that consistently exceed your provisioned capacity.

For traffic spikes, consider the strategies from the Handle traffic spikes with Amazon DynamoDB provisioned capacity blog in Additional resources.

For continuous high traffic, consider the capacity adjustment options below:

TableReadProvisionedThroughputExceeded

When this occurs

Your application's read consumption rate exceeds the provisioned read capacity units (RCUs) configured for your table. You can monitor the CloudWatch metrics in Common diagnosis and monitoring to analyze your throttling event.

Resolution approach

Consider these strategies to resolve read capacity throttling:

TableWriteProvisionedThroughputExceeded

When this occurs

Your application's write consumption rate exceeds the provisioned write capacity units (WCUs) configured for your table. You can monitor the CloudWatch metrics in Common diagnosis and monitoring to analyze your throttling event.

Resolution approach

Consider these strategies to resolve write capacity throttling:

IndexReadProvisionedThroughputExceeded

When this occurs

Read consumption on a Global Secondary Index (GSI) exceeds the GSI's provisioned read capacity units (RCUs). You can monitor the CloudWatch metrics in Common diagnosis and monitoring to analyze your throttling event.

Resolution approach

Consider these strategies to resolve GSI read capacity throttling:

IndexWriteProvisionedThroughputExceeded

When this occurs

Updates to items in the base table trigger writes to a GSI that exceed the GSI's provisioned write capacity. This causes back-pressure throttling on base table writes. You can monitor the CloudWatch metrics in Common diagnosis and monitoring to analyze your throttling event.

Resolution approach

Consider these strategies to resolve GSI write capacity throttling:

Common diagnosis and monitoring

When troubleshooting throughput errors, several CloudWatch metrics can help identify the root cause.

Essential CloudWatch metrics

Monitor these key metrics to diagnose provisioned capacity throttling:

Resolution procedures

Increasing table throughput capacity

Use this procedure when Auto Scaling is not enabled and you need immediate capacity increase.

  1. Update your table's provisioned capacity using the DynamoDB console, AWS CLI, or SDK:

    • For read capacity: Increase the ReadCapacityUnits parameter, which specifies the maximum number of strongly consistent reads consumed per second before DynamoDB throttles requests.

    • For write capacity: Increase the WriteCapacityUnits parameter, which specifies the maximum number of writes consumed per second before DynamoDB throttles requests.

  2. Verify that your new capacity settings don't exceed the per-table throughput quotas and that your total account consumption remains below the per-account throughput quotas for your Region. If you're approaching these limits, consider switching to on-demand capacity mode instead.

Configuring table Auto Scaling to adjust the read or write capacity of your table or GSI

Configure DynamoDB Auto Scaling to automatically adjust read or write capacity based on traffic patterns. You can configure Auto Scaling independently for both tables and GSIs, with separate controls for read and write capacity units.

  1. Enable Auto Scaling for read capacity, write capacity, or both on your table or GSI.

  2. Set a target utilization percentage with headroom for traffic spikes.

    Note

    Lower target utilization increases costs and scaling frequency. Targets below 40% may cause over-provisioning. Monitor usage patterns and costs to balance performance and efficiency.

  3. Set capacity boundaries:

    • Minimum RCUs/WCUs: Maintains sufficient capacity during low-traffic periods.

    • Maximum RCUs/WCUs: Accommodates peak traffic demands and protects against runaway scaling events.

For guidance on configuring and managing DynamoDB Auto Scaling, see Managing throughput capacity automatically with DynamoDB Auto Scaling.

Note

Auto Scaling typically takes several minutes to respond to traffic changes. For sudden traffic spikes, your table's burst capacity provides immediate protection while Auto Scaling adjusts. Configure target utilization with adequate headroom to allow time for scaling operations and to preserve burst capacity for unexpected demand.

Optimizing your table's or index's read or write Auto Scaling settings

Use this procedure when Auto Scaling is enabled but throttling still occurs. You can tune Auto Scaling independently for both tables and global secondary indexes (GSIs), with separate controls for read and write capacity units.

  • Adjust target utilization: Consider lowering the target utilization for your table or GSIs to trigger scaling earlier before throttling occurs. Ensure that you monitor your traffic after making these adjustments. See Configuring table Auto Scaling to adjust the read or write capacity of your table or GSI for more information about capacity consumption and cost implications.

  • Review capacity boundaries: Ensure your minimum and maximum capacity settings align with your actual workload patterns.

Switching to on-demand capacity mode

For general information about switching capacity modes, see Considerations when switching capacity modes in DynamoDB. Refer to the Service Quotas to learn about specific constraints when switching mode.

Increasing GSI throughput capacity

Use this procedure when Auto Scaling is not enabled on your GSI or you need immediate capacity increase.

  1. Update the GSI's provisioned capacity using the DynamoDB console, AWS CLI, or SDK:

    • For read capacity: Increase the ReadCapacityUnits parameter for the specific GSI, which specifies the maximum number of reads the GSI can consume per second before DynamoDB throttles requests. Note that GSIs only support eventually consistent reads.

    • For write capacity: Increase the WriteCapacityUnits parameter for the specific GSI, which specifies the maximum number of writes the GSI can consume per second before DynamoDB throttles requests.

  2. Ensure that the GSI's provisioned throughput capacity remains within the per-account and per-table throughput quotas.

Additional resources