📬Dead Letter Queue•POST /v1/dlq

Dead Letter Queue

Failure inbox for retries, inspection, and human triage of agent tasks.

What it does

Captures failed task payloads and error context so an agent or operator can inspect, retry, or hand off the failure without rerunning the whole workflow.

Endpoint

Method: POST

Path: POST /v1/dlq

Auth: x-agent-id + x-api-key

Request shape

•payload: object
•error: string
•context?: object

Example requests

Copy-pasteable examples for agents and automation.

cURL

curl -X POST https://www.agent-utils.com/v1/dlq \
  -H "x-agent-id: data-pipeline" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{
    "payload": {"fileId": "abc123", "rows": 5000},
    "error": "Column count mismatch: expected 12, got 15"
  }'

Python

import requests

resp = requests.post(
    "https://www.agent-utils.com/v1/dlq",
    headers={
        "x-agent-id": "data-pipeline",
        "x-api-key": "agutil_agt_…",
        "content-type": "application/json",
    },
    json={
        "payload": {"fileId": "abc123", "rows": 5000},
        "error": "Column count mismatch: expected 12, got 15",
    },
)
dlq_id = resp.json()["data"]["id"]

JavaScript

const res = await fetch("https://www.agent-utils.com/v1/dlq", {
  method: "POST",
  headers: {
    "x-agent-id": "data-pipeline",
    "x-api-key": "agutil_agt_…",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    payload: { fileId: "abc123", rows: 5000 },
    error: "Column count mismatch: expected 12, got 15",
  }),
});

How agents use it

An API worker stores the failing request and error message, then a separate retry agent replays it later.

A human operator reviews dead letters in a queue and decides whether to fix data or rerun the step.

An autonomous pipeline escalates unrecoverable failures into a triage workflow instead of dropping them.

When to use it

✓An external API fails and you need to preserve the original input.
✓A downstream validator rejects an agent response.
✓A multi-step workflow fails and only one step needs retrying.

When not to use it

•The task can be safely retried immediately and statelessly.
•You do not need the original payload after failure.

Failure modes

•If the payload is incomplete, retries may not be reproducible.
•Dead letters should be drained regularly or the queue becomes a dump bin.
•Retry logic must be idempotent or duplicate processing can happen.

Machine-readable summary

This JSON block is stable for crawlers, agents, and downstream documentation pipelines.

{
  "slug": "dlq",
  "title": "Dead Letter Queue",
  "canonical": "/docs/dlq",
  "endpoint": "POST /v1/dlq",
  "method": "POST",
  "auth": "x-agent-id + x-api-key",
  "machine_readable": true,
  "request_shape": [
    "payload: object",
    "error: string",
    "context?: object"
  ],
  "agent_workflows": [
    "An API worker stores the failing request and error message, then a separate retry agent replays it later.",
    "A human operator reviews dead letters in a queue and decides whether to fix data or rerun the step.",
    "An autonomous pipeline escalates unrecoverable failures into a triage workflow instead of dropping them."
  ],
  "failure_modes": [
    "If the payload is incomplete, retries may not be reproducible.",
    "Dead letters should be drained regularly or the queue becomes a dump bin.",
    "Retry logic must be idempotent or duplicate processing can happen."
  ]
}

Related docs

checkpoint kv-store