Sqs with lambda esm with batch item failures

When using Lambda with an SQS trigger in ESM format (ECMAScript modules), the way you handle batch item failures is important for determining which messages get reprocessed.

If you've enabled "Report batch item failures" on your Lambda function, you need to return a specific response format to indicate which messages failed processing. The correct approach is to return an object with a batchItemFailures array containing the message IDs that failed.

For JavaScript/Node.js in ESM format, your handler should look something like this:

export const handler = async (event, context) => {
const batchItemFailures = [];
for (const record of event.Records) {
try {
await processMessageAsync(record, context);
} catch (error) {
batchItemFailures.push({ itemIdentifier: record.messageId });
}
}
return { batchItemFailures };
};

If you're returning a status code of 400 with a JSON body message instead of this format, Lambda won't recognize which specific messages failed. In that case, the entire batch would be considered failed and all messages would be returned to the queue for reprocessing.

The correct way to handle partial batch failures is to:

1. Process each message individually
2. Catch any errors during processing
3. Add the messageId of failed messages to the batchItemFailures array
4. Return the object with the batchItemFailures array

This way, only the specific messages that failed processing will be returned to the queue, while successfully processed messages will be deleted from the queue.
Sources
Amazon SQS examples using SDK for JavaScript (v3) - AWS SDK Code Examples
Reporting batch item failures for Lambda functions with an Amazon SQS trigger - AWS Lambda