---
title: "Create dead letter"
method: POST
path: "/v2/pipelines/{pipeline_key}/dead_letters"
tags: ["Pipeline Dead Letters"]
---

# Create dead letter

`POST /v2/pipelines/{pipeline_key}/dead_letters`

Manually adds a source record to the dead letter queue for reprocessing. Use this to force a record through the pipeline again, for example when the agent or judge made an incorrect decision.

## Path parameters

- `pipeline_key` string, required — The unique key for the pipeline. You can provide the key, or the platform generates one.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- CreatePipelineDeadLetterEntryRequest — Request to manually add a source record to the dead letter queue for reprocessing. Use this when you want to force a record through the pipeline again, for example when the agent or judge made an incorrect decision.
  - `source_record_id` string, required — The identifier for the source record to add. Format depends on connector type: - S3: the object key (e.g. `legal/contracts/doc.pdf`) - SharePoint: the drive item ID - Google Drive: the file ID - Box: the file ID (e.g. `1422162456741`) - Wolken: the article number (e.g. `345678`) - Confluence: the page ID (e.g. `123456789`) - Web: the canonicalized URL (e.g. `https://docs.example.com/page`)
  - `error_message` string — Optional reason for manually adding this record.

## Response `201`

The created dead letter.

- PipelineDeadLetterEntry — A record that failed processing during a pipeline run. Dead letters are pipeline-scoped. If the same source record fails across multiple runs, the existing entry is updated, not duplicated. Resolved dead letters are deleted.
  - `id` string, required — The unique identifier for this dead letter entry.
  - `source_record_id` string, required — The identifier for the source record. Format depends on connector type: - S3: the object key (e.g. `legal/contracts/doc.pdf`) - SharePoint: the drive item ID - Google Drive: the file ID - Box: the file ID (e.g. `1422162456741`) - Wolken: the article number (e.g. `345678`) - Confluence: the page ID (e.g. `123456789`) - Web: the canonicalized URL (e.g. `https://docs.example.com/page`)
  - `status` 'pending' | 'retrying', required — The status of a dead letter entry.
  - `error_message` string, nullable — The error message from the most recent failed processing attempt.
  - `last_run_id` string — The unique identifier for a pipeline run.
  - `attempt_count` integer, required — The number of times this record has been attempted.
  - `origin` 'pipeline' | 'manual', required — How this dead letter was created.
  - `created_at` string, date-time, required — When this dead letter was first recorded.
  - `updated_at` string, date-time, nullable — When this dead letter was last updated.

## Other responses

- `400` — The request is malformed.
- `403` — Permissions do not allow creating dead letters for this pipeline.
- `404` — Pipeline not found.
- `409` — A dead letter for this source record already exists and is being retried.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/e85040b266cc/schema)