失敗したキューメッセージに対処する
max_attempts 回失敗したメッセージは dead になります。Edge は dead のメッセージを 14 日間保持するので、失敗の理由を確かめ、コンシューマーを直し、キューに戻すことができます。黙って失われることはありません。dead になるたびに queue.message.dead_lettered イベントも発生します。
このページの操作はどれもライブサイトを変えません。
ここでのキューは acme-marketing の orders(que_01M4XB7Q2W8E5R3T6Y9U1I4O0P)です。キューでバックグラウンド処理する を参照してください。
1. 発生したら知らせてもらう
Webhook を queue.message.dead_lettered に登録します。このイベントにはメッセージ本文が含まれるので、* では選ばれません。名前で指定するか、queue.* を使ってください。Edge のイベントを Webhook に送る を参照してください。
2. 何が失敗したかを見る
Web アプリで Distributions を開き、acme-marketing を選んで Queues を見ます。dead のメッセージがあるキューには、その数が表示されます。
acme-marketing の orders キューの dead メッセージと、失敗した理由を見せて。edge queues peek que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --status deadcurl -s "https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/messages?status=dead" \
-H "Authorization: Bearer $EDGE_TOKEN"エージェントは edge_queue_peek を実行します。
{
"status": "dead",
"messages": [
{
"message_id": "msg_01M4XB9D3F6G8H1J4K7L0Z2X5C",
"attempts": 5,
"last_error": "guest_status: the function answered 500",
"dead_at": "2026-10-19T03:40:12+00:00",
…
}
]
}本文には個人データが含まれうるので、既定では含まれません。見るには --bodies(include_bodies=true)を付けます。誰が何件読んだかは Edge が記録します。last_error の元になったバッチの実行は edge queues runs に、関数自身の出力は source が queue のログにあります。
last_error が expired のメッセージは、キューの retention_days の間に一度も届けられなかったものです。コンシューマーで失敗したわけではありません。
3. 戻すか、削除する
コンシューマーを直したら、redrive で dead のメッセージを試行回数をリセットしてキューに戻します。purge は完全に削除します。Web アプリでは、キューの行に Redrive dead と Purge dead があります。purge は 2 回クリックして確定します。
acme-marketing の orders キューの dead メッセージを redrive して。edge queues redrive que_01M4XB7Q2W8E5R3T6Y9U1I4O0P
# 一部だけ:
edge queues redrive que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --message msg_01M4XB9D3F6G8H1J4K7L0Z2X5C
# 削除する:
edge queues purge que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --status deadcurl -s -X POST https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/redrive \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
curl -s -X POST https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/purge \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status": "dead", "confirm": true}'エージェントは edge_queue_redrive({"redriven": 3})か edge_queue_purge({"deleted": 3})を実行します。purge は元に戻せません。また、指定した状態のメッセージだけが対象です。dead を purge しても待っているメッセージは残ります。処理中のバッチにあるメッセージが purge されることはありません。
次に
コンシューマーを直す間、新しいバッチを止めたいときはキューを一時停止します(Web アプリの Pause、または edge queues update que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --paused true)。メッセージは届き続け、再開を待ちます。メッセージの種類ごとの保持期間は 上限 にあります。