February 21, 2025

Fixing "WaitTimeSeconds is Invalid" Error in Amazon SQS

Introduction

Amazon Simple Queue Service (SQS) is like a postbox for messages in the cloud. It helps different parts of a system talk to each other by sending and receiving messages safely. However, sometimes, you might see an error like this:

"pool-12-thread-1" software.amazon.awssdk.services.sqs.model.SqsException: Value 120 for parameter WaitTimeSeconds is invalid. Reason: Must be >= 0 and <= 20, if provided. (Service: Sqs, Status Code: 400, Request ID: 6778dcd6-b3e8-59ca-a981-bce42253312d)

This error happens when the WaitTimeSeconds setting is greater than 20, which is not allowed. Let's break it down so even a child can understand and see how to fix it.

Understanding the Error

What is WaitTimeSeconds?

Think of WaitTimeSeconds like waiting at a bus stop. If you set it to 0, it's like checking for a bus and leaving immediately if there isn’t one (short polling). If you set it to a number between 1 and 20, it means you wait for some time before deciding no bus is coming (long polling). But if you try to wait more than 20 seconds, SQS says, “That’s too long!” and throws an error.

Why Does This Happen?

If the system tries to wait longer than 20 seconds, Amazon SQS stops it because that’s the maximum waiting time allowed per request.

Common reasons include:

  • Wrong settings in your application code.
  • Misunderstanding of polling rules (thinking you can wait longer than allowed).
  • Forgetting to set a valid value and using a default that is too high.

When and How to Use WaitTimeSeconds

When Should You Use It?

  • If you want to check for new messages quickly, set WaitTimeSeconds = 0 (short polling).
  • If you want to reduce unnecessary requests and save money, set WaitTimeSeconds between 1-20 (long polling).
  • If your system does not need real-time responses, use the maximum 20 seconds to lower API costs and reduce load on your application.

How to Use It Correctly

Example in AWS SDK for Java (v2):

import software.amazon.awssdk.services.sqs.model.ReceiveMessageRequest;

ReceiveMessageRequest receiveMessageRequest = ReceiveMessageRequest.builder()
    .queueUrl(queueUrl)
    .waitTimeSeconds(20) // ✅ Must be between 0 and 20
    .maxNumberOfMessages(10)
    .build();

Recommended Settings for Best Performance

Scenario Recommended WaitTimeSeconds Why?
Real-time applications 0-5 Faster response but may increase API calls.
Standard polling (normal) 10-15 Balanced approach for efficiency.
Batch processing (not urgent) 20 Reduces cost by minimizing API calls.

Fixing the Issue

1. Use a Valid WaitTimeSeconds Value

Make sure it’s between 0 and 20 to avoid errors.

2. Loop If You Need a Longer Delay

If you need more than 20 seconds, use a loop instead of setting an invalid value.

while (true) {
    ReceiveMessageRequest receiveMessageRequest = ReceiveMessageRequest.builder()
        .queueUrl(queueUrl)
        .waitTimeSeconds(20) // Maximum allowed value
        .maxNumberOfMessages(10)
        .build();

    sqsClient.receiveMessage(receiveMessageRequest);
}

3. Set Default Long Polling in Queue Settings

If you want all consumers to wait for a specific time, set the Receive Message Wait Time in the queue settings (Amazon SQS Console → Queue → Edit → Receive Message Wait Time).

Best Practices for Using Long Polling in SQS

  • Use long polling (WaitTimeSeconds > 0) to reduce API requests and costs.
  • Set WaitTimeSeconds to 20 for best efficiency and fewer requests.
  • Use batch processing (maxNumberOfMessages > 1) to optimize performance.
  • Monitor with AWS CloudWatch to track queue performance and adjust settings.
  • Implement retries with exponential backoff to handle failures properly.

Common Problems and Solutions

1. High API Costs Due to Short Polling

  • If WaitTimeSeconds=0, you’ll make too many API requests.
  • Solution: Set WaitTimeSeconds to at least 10-20 seconds.

2. Messages Take Too Long to Appear

  • If messages don’t appear, another system might be processing them due to the visibility timeout setting.
  • Solution: Check and adjust visibility timeout if necessary.

3. System Stops Receiving Messages Suddenly

  • If your app isn’t receiving messages, check if it’s not processing them fast enough.
  • Solution: Increase maxNumberOfMessages and ensure enough workers are running.

Further Reading

Conclusion

The "WaitTimeSeconds is invalid" error in Amazon SQS happens when you set an invalid value above 20. To fix it:

  1. Set WaitTimeSeconds between 0-20.
  2. Use a loop if you need longer delays.
  3. Configure queue settings for default long polling.
  4. Follow best practices for cost and performance efficiency.

By following these recommendations, you can use SQS more effectively, reduce API costs, and avoid common pitfalls. Happy coding! 🚀

Posted by
Labels: