DLQ

The dead-letter queue is where failed work becomes inspectable. It is the place to answer whether a bad payload, a permanent handler failure, or exhausted retries pushed a run off the happy path.

Use it to answer:

• what failed by looking at kind, err_msg, original body, and the captured envelope
• whether it was retryable by checking whether the final record is a permanent failure or a retries-exhausted failure
• which service or action produced the failure by reading service, action, subject, and flow_run_id

For SDK-produced failures, the common kind values are permanent and retries_exhausted. The inspection store also keeps enough context to correlate a DLQ entry back to one run: flow_run_id, the full envelope, and JetStream sequence metadata.

The current inspection endpoints are:

• /api/v2/dlq/source for the latest entries across the system
• /api/v2/dlq/source/:flow_run_id for all DLQ entries tied to one run
• /api/v2/dlq/services/:service/:action for one service-action pair
• /api/v2/dlq/entries/:id for a single full record

The Mongo inspection collection currently has an 8 day TTL. Treat it as a debugging surface, not as a permanent archive.