History & DLQ

Every delivery attempt writes a row to /v1/delivery/items with its status, HTTP code, error code, and request/response bodies (truncated to 10 KB each). Terminal failures (retry ladder exhausted or permanent 4xx) escalate to /v1/delivery/dlq. Both are fully replayable — replay enqueues a new attempt while preserving the deterministic idempotency key, so receivers that deduplicate on the key will not process the same delivery twice even after multiple replays. Nothing in history is ever mutated; the log is strictly append-only.

The delivery items log captures the full lifecycle of each attempt: in-flight, succeeded, or failed. Each row includes the attempt number, HTTP status code, error code, duration in milliseconds, and truncated request/response bodies (up to 10 KB each). Use the items endpoint with filters for binding_id, destination_id, or status to narrow results when debugging a specific integration. Item and DLQ IDs are UUIDs, while event IDs are sequential integers for efficient ordering.

The dead letter queue (DLQ) is your safety net for terminal failures. When the retry ladder is exhausted (default: 7 attempts over ~10 hours) or the destination returns a permanent error (e.g., 401 Unauthorized, 403 Forbidden), the failed delivery moves to the DLQ. From there you can inspect the error details, fix the destination configuration, and replay the delivery with a single click or API call. Destinations returning authentication errors are automatically disabled to prevent further failed attempts until the credentials are updated.

For best results, monitor the DLQ regularly and set up a delivery.item.failed meta-signal binding to receive alerts when deliveries fail terminally. Most teams configure a notification webhook for this signal so they are notified immediately rather than discovering failures during a manual review. Request and response bodies older than the configured retention period are automatically cleaned up, but row metadata (status, error code, duration) is retained indefinitely.

# List delivery attempts for a binding:
curl -s "https://api.talonic.com/v1/delivery/items?binding_id=bind_001&limit=5" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response:
# {
#   "items": [
#     {
#       "id": "item_abc",
#       "status": "succeeded",
#       "attempt": 1,
#       "http_status": 200,
#       "duration_ms": 142,
#       "completed_at": "2025-04-22T10:05:00Z"
#     }
#   ]
# }

# Check the DLQ for terminal failures:
curl -s "https://api.talonic.com/v1/delivery/dlq?binding_id=bind_001" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Replay a dead-letter entry (new attempt=1, same idempotency key):
curl -X POST https://api.talonic.com/v1/delivery/dlq/dlq_xyz/replay \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "replayed": true }

The delivery history and DLQ together provide complete observability into your outbound data flow. Every attempt is logged with precise timing, HTTP status, error classification, and truncated request/response bodies for debugging. When a delivery fails terminally, the DLQ captures the full context — which event triggered it, which binding matched, what error occurred, and how many attempts were made. Replay is safe to run multiple times because the idempotency key is deterministic: receivers that deduplicate on the X-Talonic-Idempotency-Key header will not process the same delivery twice, even after multiple replays. Destinations that return authentication errors (401, 403) are automatically disabled to prevent a cascade of failed attempts from consuming your retry budget.