Skip to main content

Dead Letter Queue

Inspect and manage permanently failed deliveries in the dead letter queue. Replay individual items or discard them.

Deliveries that exhaust all retry attempts are moved to the dead letter queue (DLQ). Items in the DLQ can be inspected, replayed (enqueues a fresh attempt), or deleted.

The DLQ is the terminal state for failed deliveries. Common error codes include connector_5xx (destination returned a server error), auth_failed (invalid credentials), ssrf_blocked (destination URL resolves to a private network), and payload_too_large (payload exceeds the cap). Non-retryable errors (auth_failed, ssrf_blocked) skip the retry ladder and go directly to the DLQ.

DLQ replay deletes the dead-letter row before enqueuing the new attempt. If the enqueue fails, the DLQ row is lost. This is an intentional trade-off: the system prefers losing a DLQ row over duplicating a delivery.
GET/v1/delivery/dlq

Response

Response fields

dataarrayArray of dead-letter records.
data[].idstringDead-letter item UUID.
data[].binding_idstringBinding that produced this failure.
data[].event_idstringOutbox event ID (BIGSERIAL, as string).
data[].last_item_idstring | nullUUID of the last delivery attempt item.
data[].error_codestringMachine-readable error code (e.g. `connector_5xx`, `auth_failed`, `ssrf_blocked`, `payload_too_large`).
data[].error_messagestring | nullHuman-readable error message.
data[].attemptsintegerTotal number of delivery attempts made before reaching the DLQ.
data[].created_atstringISO 8601 timestamp when the item entered the DLQ.

Response

{
  "data": [
    {
      "id": "f6a7b8c9-d0e1-2345-fabc-567890123456",
      "binding_id": "d4e5f6a7-b8c9-0123-defa-345678901234",
      "event_id": "98750",
      "last_item_id": "e5f6a7b8-c9d0-1234-efab-456789012345",
      "error_code": "connector_5xx",
      "error_message": "HTTP 503",
      "attempts": 7,
      "created_at": "2024-09-16T03:00:00.000Z"
    }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.
POST/v1/delivery/dlq/:id/replay

Response

Response fields

replayedbooleanAlways true on success. The DLQ row is deleted and a new delivery attempt is enqueued.

Response

{
  "replayed": true
}

Errors

Error responses

400bad_requestReplay is not available in master view (organization-wide API key).
401unauthorizedMissing or invalid API key.
404not_foundNo DLQ item with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.
DELETE/v1/delivery/dlq/:id

Response

Response fields

dismissedbooleanAlways true on success.

Response

{
  "dismissed": true
}

Errors

Error responses

400bad_requestDismiss is not available in master view (organization-wide API key).
401unauthorizedMissing or invalid API key.
404not_foundNo DLQ item with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Delivery History
List Destinations