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 someone deals with them.

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

Terminal window
# All examples assume $TOKEN is an API key (hv_...)
AUTH="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)
Terminal window
curl "http://127.0.0.1:3000/admin/dead-letters?limit=10" -H "$AUTH"

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
Terminal window
curl "http://127.0.0.1:3000/admin/dead-letters/count" -H "$AUTH"

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.

Terminal window
curl "http://127.0.0.1:3000/admin/dead-letters/42" -H "$AUTH"

Response: 200 OK

The response includes all fields from the list view plus a record field containing the original record data (if available). 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.

Terminal window
curl -X POST "http://127.0.0.1:3000/admin/dead-letters/42/dismiss" -H "$AUTH"

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

Returns 404 if the dead letter is not found.

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 cannot be retried — the upstream label event is gone. These return 400 Bad Request.

Terminal window
curl -X POST "http://127.0.0.1:3000/admin/dead-letters/42/retry" -H "$AUTH"

Response: 200 OK — {"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. On success the dead letter is marked resolved. Label-arrival dead letters cannot be reindexed and return 400 Bad Request.

Terminal window
curl -X POST "http://127.0.0.1:3000/admin/dead-letters/42/reindex" -H "$AUTH"

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

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.

Terminal window
curl -X POST "http://127.0.0.1:3000/admin/dead-letters/bulk/dismiss" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["42", "43", "44"]}'

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

Bulk retry

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

Retry multiple dead letters. Accepts the same input as bulk dismiss. Stops at the first failure and returns it; dead letters handled before it stay resolved.

Terminal window
curl -X POST "http://127.0.0.1:3000/admin/dead-letters/bulk/retry" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"all": true, "collection": "xyz.statusphere.status"}'

Response: 200 OK — {"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. Stops at the first failure and returns it; dead letters handled before it stay resolved.

Terminal window
curl -X POST "http://127.0.0.1:3000/admin/dead-letters/bulk/reindex" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"all": true}'

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

© HappyProto