はじめに
一件の不正payloadでconsumerが毎回停止すると、その後ろにある正常な仕事まで処理できません。例外を握りつぶしてskipすると、今度は失敗した一件が消えます。Dead Letter Queue(DLQ)はこの二択を避け、処理不能なitemを証拠付きで隔離する仕組みです。
ただし、DLQへ移しただけでは復旧していません。なぜ失敗したか、再投入できる条件は何か、元の順序を守る必要があるか、重複をどう防ぐか、成功を何で確認するかまで契約化する必要があります。
この記事ではPythonのqueue worker、dead letter schema、dependency単位の停止、requeue、dry-run、負試験を説明します。
retryとdead letterを分ける
一時エラーは短いretryで回復する可能性があります。schema不正、認証拒否、承認欠落のような恒久エラーは同じpayloadを繰り返しても直りません。
from enum import Enum
class FailureKind(str, Enum):
TRANSIENT = "transient"
PERMANENT = "permanent"
UNKNOWN = "unknown"
def classify(error):
if isinstance(error, (TimeoutError, RateLimitError, ServiceUnavailable)):
return FailureKind.TRANSIENT
if isinstance(error, (SchemaError, AuthError, ApprovalError)):
return FailureKind.PERMANENT
return FailureKind.UNKNOWN
transientはattempt budgetとdeadline内だけretryします。permanentは即DLQへ送ります。unknownは外部作用前と証明できなければReconciliationへ送り、未実行と決めつけません。
すべての例外をDLQへ入れる設計も危険です。503のたびに人手対応が必要になり、DLQが本来の「修正が必要なitem」を表さなくなります。
Dead Letter schemaに復旧条件を入れる
DLQ recordは元payloadの墓場ではなく、復旧作業票です。
{
"schema": "dead-letter/v1",
"dead_letter_id": "dlq_20260722_001",
"message_id": "msg_0088",
"route_id": "agent_memories_official",
"payload_sha256": "1f8c...",
"failure_kind": "permanent",
"reason_code": "approval_missing",
"attempts": 1,
"first_failed_at": "2026-07-22T00:00:00Z",
"last_failed_at": "2026-07-22T00:00:00Z",
"requeue_condition": "fresh_alice_approval",
"dependency_key": "article:example-slug",
"external_effect_id": null
}
payload全文、secret、Cookie、Authorization headerは保存しません。元payloadは安全なartifact storageへ置き、DLQ recordはpathとhashで参照します。
dependency_keyは停止範囲を決めます。同じ親投稿に紐づく子リプは親が確定するまで進めませんが、別articleや別routeの仕事は継続できます。
queue全体ではなくdependencyを止める
FIFOを厳密に守る必要がない独立jobなら、失敗itemを隔離して後続を処理します。
def consume(batch, handler, dlq):
outcomes = []
blocked_dependencies = set()
for item in batch:
if item.dependency_key in blocked_dependencies:
outcomes.append(skip(item, "dependency_blocked"))
continue
try:
outcomes.append(handler(item))
except Exception as error:
kind = classify(error)
if kind is FailureKind.TRANSIENT and item.retry_budget > 0:
outcomes.append(schedule_retry(item, error))
continue
dlq.append(to_dead_letter(item, error, kind))
blocked_dependencies.add(item.dependency_key)
outcomes.append(isolate(item, error))
return outcomes
ここでblocked_dependenciesをroute全体へ広げないことがポイントです。article Aのapproval不足でarticle Bのread-only分析まで止めません。
一方、銀行取引のようにglobal orderが業務invariantなら、後続継続は危険です。その場合はpartition keyを設計し、同じpartitionだけ止めます。独立性は実装都合で決めず、外部作用の関係から決めます。
requeueは元messageをそのまま戻さない
失敗原因が直った後も、古いpayloadが現在の承認やrouteと一致するとは限りません。再投入前にpreconditionを再検査します。
function canRequeue(letter: DeadLetter, current: CurrentState): RequeueDecision {
if (letter.payloadSha256 !== current.payloadSha256) {
return { ok: false, reason: "payload_changed_requires_new_message" };
}
if (!current.approvalValid || current.approvedHash !== letter.payloadSha256) {
return { ok: false, reason: "fresh_approval_required" };
}
if (current.routeId !== letter.routeId || !current.accountIdentityMatch) {
return { ok: false, reason: "route_or_account_mismatch" };
}
if (current.expiresAt <= new Date()) {
return { ok: false, reason: "payload_expired" };
}
return { ok: true, reason: "preconditions_satisfied" };
}
本文が変わった場合、同じdead letterを上書きして戻さず、新しいmessage IDとhashを発行します。旧DLQ recordはsuperseded_byで紐づけ、なぜ使わなかったかを残します。
requeue時にはdead_letter_idから一意なidempotency keyを作り、複数担当が同時に戻してもqueueへ一件だけ入るようにします。
再投入の順序と期限を管理する
復旧itemをqueue先頭へ戻すと、古い情報が最新itemより先に公開される可能性があります。優先度は業務ルールで決めます。
def choose_requeue_slot(letter, schedule, now):
if parse_time(letter.expires_at) <= now:
return Decision("drop", "expired")
if letter.requires_original_order:
return schedule.after_dependency(letter.dependency_key)
return schedule.next_available(
after=now,
minimum_gap_minutes=letter.minimum_gap_minutes,
)
日次記事なら公開cadenceを守り、次の空き枠へ移します。速報なら期限切れとしてdropし、作り直しキューへ送ります。親子messageは親のreadback後に子を再投入します。
dropも黙って削除しません。dropped_expired、superseded、manual_actionとしてterminal Receiptを残し、在庫数や後続scheduleを更新します。
DLQをatomicかつ追跡可能にする
元queueから削除してからDLQ保存に失敗するとitemが消えます。可能なら同じtransaction内でmoveし、ファイルベースならDLQ保存完了後に元messageをackします。
BEGIN;
INSERT INTO dead_letters (
dead_letter_id, message_id, route_id, payload_sha256, reason_code, state
) VALUES (?, ?, ?, ?, ?, 'isolated');
UPDATE queue_messages SET state = 'dead_lettered' WHERE message_id = ? AND state = 'processing';
COMMIT;
affected rowが1であることを確認します。0ならlease喪失、2以上ならschema破壊です。transactionが使えない外部queueではoutbox patternやdedupe keyで同等の保証を作ります。
監視はDLQ件数だけでなく、最古age、reason別件数、requeue可能件数、manual action件数を見ます。一件増えた時と復旧した時に通知し、毎run同じ警告を繰り返しません。
負試験で「消失」と「全停止」を作る
DLQ設計は障害注入で検証します。
def test_permanent_failure_does_not_stop_independent_items():
items = [item("a", dep="article:a"), item("b", dep="article:b")]
handler.fail("a", ApprovalError())
result = consume(items, handler, dlq)
assert result[0].status == "isolated"
assert result[1].status == "success"
assert len(dlq) == 1
def test_dlq_write_failure_does_not_ack_source_message():
dlq.fail_next_write()
with pytest.raises(StorageError):
consume([item("a")], handler_that_fails, dlq)
assert source_queue.state("a") == "processing"
追加で、同じdependencyの後続skip、別dependency継続、payload変更後requeue拒否、期限切れdrop、二重requeue、lease expiry、unknown外部effect、DLQ record破損を試します。dry-runは対象letter、判定、予定slotを出しますが、queue writeと外部writeは0にします。
完了条件は、message消失0、独立後続成功、同一dependency順序維持、requeue重複0、最終readback一致です。
まとめ
Dead Letter Queueは失敗itemを横へ移すだけの箱ではありません。failure分類、復旧条件、dependency boundary、payload hash、承認、期限、requeue idempotency、readbackを持つ復旧契約です。
恒久エラー一件を隔離し、正常な後続を継続しながら、原因が直った時だけ安全に再投入する。これにより「全部止める」と「失敗を捨てる」の間を実装できます。AIエージェントの記憶にも、dead letterの理由と次の条件を残せば、別セッションや別担当が同じ事故を繰り返さず復旧できます。

