Skip to content
HappyView

Dead letters

Events that failed all retry attempts are stored as dead letters for inspection and manual resolution. Dead letters come from two sources: the legacy record-index path (happyview_dead_letter_hooks) and trigger-keyed scripts (happyview_dead_letter_scripts). Both tables are surfaced through a single unified API.

Resolved script dead letters are deleted once they have been resolved for DEAD_LETTER_RETENTION_DAYS days (30 by default; see Configuration). Unresolved ones are kept until an operator dismisses, retries or reindexes them.

Read endpoints require dead-letters:read. Action endpoints (dismiss, retry, reindex) require dead-letters:manage.

const TOKEN = "hv_..."; // your API key
const headers = { Authorization: `Bearer ${TOKEN}` };

List dead letters

Section titled “List dead letters”
GET /admin/dead-letters

Paginated list of dead letters from both tables, merged and sorted by created_at descending.

ParamTypeRequiredDescription
collectionstringnoFilter by collection NSID
resolvedstringno"false" (default, unresolved only), "true" (resolved only), or any other value such as "all" for both
cursorstringnoPagination cursor from a previous response
limitnumbernoMax results per page, 1 to 100 (default 50)
const response = await fetch("http://127.0.0.1:3000/admin/dead-letters?limit=10", {
  headers,
});
const data = await response.json();

Response: 200 OK

{
  "dead_letters": [
    {
      "id": "42",
      "lexicon_id": "xyz.statusphere.status",
      "uri": "at://did:plc:abc/xyz.statusphere.status/3k...",
      "did": "did:plc:abc",
      "collection": "xyz.statusphere.status",
      "rkey": "3k...",
      "action": "create",
      "error": "script error: attempt to index nil value",
      "attempts": 4,
      "created_at": "2026-06-01T12:00:00Z"
    }
  ],
  "cursor": "2026-06-01T11:00:00+00:00"
}

Resolved dead letters include a resolved_at timestamp. cursor is the last row’s created_at, and is returned only when there are more rows.

For label rows, action is "label", lexicon_id is the script’s trigger id, did is the labeler’s DID and rkey is the label value.

Count dead letters

Section titled “Count dead letters”
GET /admin/dead-letters/count

Returns the total count of dead letters across both tables.

ParamTypeRequiredDescription
collectionstringnoFilter by collection NSID
resolvedstringno"false" (default, unresolved only), "true" (resolved only), or any other value such as "all" for both
const response = await fetch("http://127.0.0.1:3000/admin/dead-letters/count", {
  headers,
});
const data = await response.json();

Response: 200 OK

{
  "count": 7
}

Get dead letter detail

Section titled “Get dead letter detail”
GET /admin/dead-letters/{id}

Returns the full dead letter including the record body.

const response = await fetch("http://127.0.0.1:3000/admin/dead-letters/42", {
  headers,
});
const data = await response.json();

Response: 200 OK

The response includes all fields from the list view plus a record field. For a record dead letter it holds the original record data, or null when none was kept; for a label dead letter it holds the whole label. Returns 404 if the dead letter is not found.

Dismiss a dead letter

Section titled “Dismiss a dead letter”
POST /admin/dead-letters/{id}/dismiss

Marks a dead letter as resolved without retrying it.

const response = await fetch("http://127.0.0.1:3000/admin/dead-letters/42/dismiss", {
  method: "POST",
  headers,
});
const data = await response.json();

Response: 200 OK with {"ok": true}

Returns 404 if the dead letter is not found. Dismissing a dead letter that is already resolved succeeds and sets its resolved_at to the current time.

Retry a dead letter

Section titled “Retry a dead letter”
POST /admin/dead-letters/{id}/retry

Re-runs the dead letter’s script with the original event payload. On success the dead letter is marked resolved. On failure the error and attempt count are updated, and the request returns 500 Internal Server Error. A dead letter with an unknown action returns 400 Bad Request.

Label-arrival dead letters can’t be retried, because the upstream label event is gone. These return 400 Bad Request.

const response = await fetch("http://127.0.0.1:3000/admin/dead-letters/42/retry", {
  method: "POST",
  headers,
});
const data = await response.json();

Response: 200 OK with {"ok": true}

Returns 404 if no matching script binding is found, or if the dead letter is not found or already resolved.

Reindex a dead letter

Section titled “Reindex a dead letter”
POST /admin/dead-letters/{id}/reindex

Fetches the record fresh from the author’s PDS and re-runs the full record indexing pipeline. Once the PDS has returned the record, the dead letter is marked resolved, whatever the pipeline then does with it. A PDS that can’t be reached or answers with an error returns 500 Internal Server Error and leaves the dead letter unresolved. Label-arrival dead letters cannot be reindexed and return 400 Bad Request.

const response = await fetch("http://127.0.0.1:3000/admin/dead-letters/42/reindex", {
  method: "POST",
  headers,
});
const data = await response.json();

Response: 200 OK with {"ok": true}

Returns 404 if the dead letter is not found or already resolved.

Bulk dismiss

Section titled “Bulk dismiss”
POST /admin/dead-letters/bulk/dismiss

Dismiss multiple dead letters at once.

FieldTypeRequiredDescription
idsstring[]noList of dead letter IDs to dismiss
allbooleannoSet to true to dismiss all unresolved dead letters
collectionstringnoWhen all is true, limit to this collection

One of ids or all: true is required; without either the request returns 400 Bad Request. When all is true, ids is ignored.

const response = await fetch("http://127.0.0.1:3000/admin/dead-letters/bulk/dismiss", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ids: [
      "42",
      "43",
      "44"
    ]
  }),
});
const data = await response.json();

Response: 200 OK with {"ok": true}

With ids, the dead letters are dismissed in order, and the first id that matches no dead letter stops the request with 404. The ones before it stay dismissed.

Bulk retry

Section titled “Bulk retry”
POST /admin/dead-letters/bulk/retry

Retry multiple dead letters. Accepts the same input as bulk dismiss.

const response = await fetch("http://127.0.0.1:3000/admin/dead-letters/bulk/retry", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    all: true,
    collection: "xyz.statusphere.status"
  }),
});
const data = await response.json();

Response: 200 OK, with one entry per dead letter in the order they were tried. A dead letter that fails doesn’t stop the rest. Its entry carries the error, and the top-level ok is false unless every one succeeded:

{
  "ok": false,
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "id": "42", "ok": true },
    { "id": "43", "ok": false, "error": "not found: dead letter 43 not found or already resolved" },
    { "id": "44", "ok": true }
  ]
}

Bulk reindex

Section titled “Bulk reindex”
POST /admin/dead-letters/bulk/reindex

Reindex multiple dead letters. Accepts the same input as bulk dismiss.

const response = await fetch("http://127.0.0.1:3000/admin/dead-letters/bulk/reindex", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    all: true
  }),
});
const data = await response.json();

Response: 200 OK, in the same shape as bulk retry: one entry per dead letter, and a failure doesn’t stop the rest.

© HappyProto