AWS Lambda
Developer Guide

Dead Letter Queues

Any Lambda function invoked asynchronously is retried twice before the event is discarded. If the retries fail and you're unsure why, use Dead Letter Queues (DLQ) to direct unprocessed events to an Amazon SQS queue or an Amazon SNS topic to analyze the failure.

AWS Lambda directs events that cannot be processed to the specified Amazon SNS topic topic or Amazon SQS queue. Functions that don't specify a DLQ will discard events after they have exhausted their retries. For more information about retry policies, see AWS Lambda Retry Behavior.

You configure a DLQ by specifying the Amazon Resource Name TargetArn value on the Lambda function's DeadLetterConfig parameter.

{ "Code": { "ZipFile": blob, "S3Bucket": "string", "S3Key": "string", "S3ObjectVersion": "string" }, "Description": "string", "FunctionName": "string", "Handler": "string", "MemorySize": number, "Role": "string", "Runtime": "string", "Timeout": number "Publish": bool, "DeadLetterConfig": { "TargetArn": "string" } }

In addition, you need to add permissions to the execution role of your Lambda function, depending on which service you have directed unprocessed events:

The payload written to the DLQ target ARN is the original event payload with no modifications to the message body. The attributes of the message, described next, contain information to help you understand why the event wasn’t processed:

Name Type Value
RequestID String Unique request identifier
ErrorCode Number 3-digit HTTP error code
ErrorMessage String Error message (truncated to 1 KB)

If the event payload consistently fails to reach the target ARN, AWS Lambda increments a CloudWatch metric called DeadLetterErrors and then deletes the event payload.

If you are using Amazon SQS as an event source, we recommend configuring a DLQ on the Amazon SQS queue itself and not the Lambda function. For more information, see Amazon SQS Dead-Letter Queues.