Why is my Kinesis Data Stream returning a 500 Internal Server Error?

2 minute read

I want to troubleshoot Amazon Kinesis Data Stream 500 Internal Server Errors or a 503 Service Unavailable Errors.

Short Description

When you produce to a Kinesis data stream, the following internal errors can occur:

  • PutRecord or PutRecords returns an AmazonKinesisException 500 or AmazonKinesisException 503 error with a rate above 1% for several minutes
  • SubscribeToShard.Success or GetRecords returns an AmazonKinesisException 500 or AmazonKinesisException 503error with a rate above 1% for several minutes

To troubleshoot these internal errors, complete the following steps:

  1. Calculate your error rate.
  2. Implement a retry mechanism.


Calculate your error rate

Look for significant drops in the time windows of either PutRecord.Success or GetRecord.Success. You can review these metrics under the Monitoring tab. If there are significant drops, then calculate the error rate to determine the severity of your Kinesis data stream issue.
To calculate your error rate, compute the average value of PutRecord.Success and GetRecord.Success.

Implement a retry mechanism

Confirm that the error rate falls below 0.1%. Kinesis Data Streams allows for high throughput writes with a low error rate. Average error rates are typically below 0.01%.

If you wrote your own consumer or producer, then implement a retry mechanism in your application code. For more information about retry mechanism implementations, see the Retries section in Implementing efficient and reliable producers with the Amazon Kinesis Producer Library.

If your error rate exceeds 1% for several minutes, then contact AWS Support. Include the following information in your communications:

  • Applications used to read or write data to and from Data Streams
  • Number of shards in your Kinesis data stream
  • Server-side encryption settings
  • Specific shard IDs that are impacted
  • Time frame where drops in success rates are observed
  • Request IDs that are reporting internal failures

Related Information

Developing producers using the Amazon Kinesis Producer Library

Developing KCL 2.x consumers

AWS OFFICIALUpdated 4 months ago