For asynchronous AWS Lambda invocations, what is the difference between an on-failure destination and the older DeadLetterConfig dead-letter queue, and which should you configure on a new function?

## Why either one exists An asynchronously invoked function has no response channel. When Lambda exhausts its retries or the event exceeds its maximum age, the event is discarded and the original caller — long gone, holding a 202 — never learns anything. Both mechanisms in this question exist to give that dying event somewhere to land. ## DeadLetterConfig: the original `DeadLetterConfig` is a property of the function itself, holding a single `TargetArn` that must be an SQS queue or an SNS topic. When the retries run out, Lambda forwards the **original event payload** to that target. Diagnostic information travels as message attributes rather than in the body: the request ID, an error code and an error message. ```bash aws lambda update-function-configuration \ --function-name my-function \ --dead-letter-config TargetArn=arn:aws:sqs:eu-west-1:111122223333:my-dlq ``` It works, and plenty of production functions still use it. Its limits are that you get the input but not the function's actual error response, you cannot tell from the body why the event died, and there is no equivalent for successful invocations. ## Destinations: the current mechanism Destinations are set on the function's asynchronous invocation configuration through `PutFunctionEventInvokeConfig`, in a `DestinationConfig` with two independent slots: `OnFailure` and `OnSuccess`. ```bash aws lambda put-function-event-invoke-config \ --function-name my-function \ --destination-config '{"OnFailure":{"Destination":"arn:aws:sqs:eu-west-1:111122223333:failed-events"}}' ``` Four target types are supported: an SQS queue, an SNS topic, an EventBridge event bus, and another Lambda function. The EventBridge and Lambda targets are what make destinations feel like a routing primitive rather than a rubbish bin — you can fan a failure out to several handlers by rule, or hand it to a compensating function directly. What arrives is not the bare event but a JSON record wrapping it, carrying: - `requestContext` — including `requestId`, `functionArn`, `approximateInvokeCount`, and a `condition` field naming the reason the event ended up here: `RetriesExhausted`, `EventAgeExceeded`, or `ZeroReservedConcurrency`. - `requestPayload` — the original event, so replay is possible. - `responseContext` and `responsePayload` — the function's own error output. That `condition` field is the practical difference. "The dependency was down and we exhausted retries" and "this event sat in the queue for six hours" and "the function had zero reserved concurrency" are three completely different incidents, and with a DLQ you would be reconstructing which one happened from logs. ## Things that catch people out **Permissions.** The delivery is performed using the function's **execution role**, so that role needs `sqs:SendMessage`, `sns:Publish`, `events:PutEvents` or `lambda:InvokeFunction` on the target as appropriate. Miss it and the capture silently fails — the whole safety net does nothing. Watch the `DestinationDeliveryFailures` metric (and `DeadLetterErrors` for the older mechanism); an alarm on either is not optional if you rely on the capture. **Precedence.** If a function has both a `DeadLetterConfig` and an `OnFailure` destination, the destination is used. Do not configure both and expect two copies. **Scope.** Destinations described here apply to asynchronous invocation. Poller-based event sources have their own failure-handling configuration, which is a different mechanism with different fields. **Encryption.** If the target queue or topic uses a customer managed KMS key, the execution role needs key permissions too — a common cause of a capture path that tests fine against an unencrypted queue and fails in production. ## Which to choose For a new function: an on-failure destination, essentially always. Use `OnSuccess` more sparingly — it is genuinely useful for chaining a downstream step off a successful asynchronous invocation without the function knowing about its successor, but it also doubles your event volume into whatever consumes it. Keep the older DLQ only where it already exists and works, and treat migrating it as low-risk cleanup rather than urgent. Whichever you pick, the capture is only half the job. Someone has to look at the failure target, and a queue of dead events nobody drains is a compliance artefact, not a recovery mechanism. Alarm on its depth, and make replay safe by keeping the handler idempotent.