ProvisionedThroughputExceededException: The level of configured provisioned throughput for the table was exceeded

What it means

DynamoDB allocates throughput per partition, not just per table, and that single fact explains most of the surprise this exception causes. A table's capacity — provisioned or on-demand — is distributed across its partitions, and each partition has a hard ceiling of its own. A table nowhere near its configured limit can therefore throttle continuously if the traffic is concentrated on one key.

That is the difference between the two shapes of this failure. Broadly distributed throttling means the table needs more capacity, and raising it works. Throttling concentrated on one partition key means the table has plenty of unused capacity that the hot key cannot reach, and raising the number changes nothing. The keys involved in the failures tell them apart, and it is worth checking before provisioning more.

Lambda makes both shapes arrive faster than they otherwise would, because concurrency multiplies request rate. A function issuing five writes per invocation is issuing five hundred concurrent writes at a hundred concurrent executions, and Lambda will happily go from one execution to hundreds within seconds when a queue backs up or a scheduled job fans out. The table sees a step change rather than a ramp, which is also why on-demand tables throttle during spikes — on-demand adapts to traffic, but it adapts over minutes, not instantly.

The quietest version of this problem is the one that never raises an exception at all. The AWS SDKs retry throttled requests with backoff, so moderate throttling is absorbed and shows up only as invocations that take noticeably longer than they used to. And BatchWriteItem does not throw for a partially-throttled batch — it returns the remainder in UnprocessedItems, which code that ignores the field silently discards. A rising p95 duration with no errors is often the first symptom, arriving well before anything appears in a log as a failure.

What it looks like in CloudWatch

This is the shape the failure arrives in: the lines of one invocation scattered among everything else the log group received at the same moment.

The panel on the right is generated by running the excerpt on the left through the same parser that powers the free web stitcher — it is what the tool actually produces for this input, not an illustration of it.

How to confirm it from the logs

First establish whether the exception escaped or was absorbed. The SDKs retry throttled DynamoDB requests with backoff, so a logged exception generally means the retries were exhausted. A REPORT duration much longer than usual, with no error at all, is the same throttling absorbed successfully — and is the earlier warning.

Then look at whether the affected keys are the same across failures. Throttling spread evenly across many keys points at overall capacity; throttling concentrated on one partition key points at a hot partition, which more capacity will not fix because a single partition has its own ceiling regardless of the table's total.

Causes, most likely first

Fixes

yamlResources:
  OrdersTable:
    Type: AWS::DynamoDB::Table
    Properties:
      BillingMode: PAY_PER_REQUEST   # was PROVISIONED

js// Hot: every event for a given day lands on one partition.
// const pk = `ORDERS#${day}`;

// Spread across N partitions, then fan the query out over the same N.
const SHARDS = 10;
const pk = `ORDERS#${day}#${Math.floor(Math.random() * SHARDS)}`;

yamlResources:
  IngestFunction:
    Type: AWS::Serverless::Function
    Properties:
      ReservedConcurrentExecutions: 20
      Events:
        Queue:
          Type: SQS
          Properties:
            BatchSize: 25

jslet request = { RequestItems: { orders: writes } };
for (let attempt = 0; attempt < 5; attempt += 1) {
  const result = await client.send(new BatchWriteItemCommand(request));
  const left = result.UnprocessedItems?.orders ?? [];
  if (left.length === 0) break;
  await sleep(2 ** attempt * 50);
  request = { RequestItems: { orders: left } };
}

Also seen as

The same underlying failure, worded differently by a different runtime, SDK version, or logging layer. All of these land here — there is no separate page for each phrasing.

Related errors

Errors that show up alongside this one, or that people mistake for it.

References

• Amazon DynamoDB Developer Guide — Throttling and hot partitions
• Amazon DynamoDB Developer Guide — Read/write capacity mode