Dead letters

When a record fails processing during a pipeline run, it's added to the pipeline's dead letter queue. Dead letters let you inspect failures, retry them selectively, and recover from transient issues without rerunning the whole pipeline.

When dead letters are created

A record is dead-lettered when:

• The agent session throws an exception while processing the file.
• The agent completes but the configured verification fails (condition returns false, or the judge agent returns success: false).

The pipeline run itself continues — other records are still processed. The run is marked completed when all records have been attempted, but records_failed will reflect the count of dead letters.

Deduplication

Dead letters are scoped per pipeline and per source record ID. If the same record fails across multiple runs, the existing dead letter entry is updated (not duplicated). The attempt_count field tracks how many times the record has been retried.

List dead letters

LIST DEAD LETTERS

Code example with bash syntax.bash

1

Example response:

DEAD LETTERS RESPONSE

Code example with json syntax.json

1

Filters

Query param	Description
status	Filter by pending or retrying.
last_run_id	Only dead letters from a specific run. Useful for triaging a run that failed unexpectedly.
origin	Filter by pipeline (auto-created) or manual (you added it explicitly).

Retry dead letters

Retrying creates a new pipeline run that re-fetches the specified records from the source and sends them through the agent again. Successfully processed records are automatically removed from the dead letter queue.

Retry all pending dead letters

RETRY ALL PENDING DEAD LETTERS

Code example with bash syntax.bash

1

Retry specific records

RETRY SPECIFIC RECORDS

Code example with bash syntax.bash

1

Retry from a specific run

Useful when a run had an unusual failure pattern (e.g. an upstream outage) and you want to retry only those records.

RETRY DEAD LETTERS FROM A RUN

Code example with bash syntax.bash

1

Only one run can be active per pipeline at a time. If the pipeline is already running when you call /process, the request returns 409 Conflict.

Manually add a dead letter

Sometimes the agent (or judge) makes an incorrect decision — it might discard a record that should have been processed, or skip something it shouldn't have. You can force a record through the pipeline again by adding it to the dead letter queue manually:

MANUALLY ADD A DEAD LETTER

Code example with bash syntax.bash

1

Manually added dead letters have origin: manual so you can distinguish them from automatic failures.

Delete a dead letter

If you want to dismiss a known failure that shouldn't be retried (e.g. a corrupted file that will never process successfully), you can delete the dead letter directly:

DELETE A DEAD LETTER

Code example with bash syntax.bash

1

Deleting a dead letter does not delete the source record — it only removes it from the queue. If the record later appears in a pipeline run and fails again, a new dead letter will be created.