> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # List DLQ Messages > Use this endpoint to list messages currently in the webhook dead-letter queue, scoped to the caller's tenant. The tenant is derived from the bearer JWT (`tenantId` claim), never from a request header. This route is only mounted when authentication is enabled and a DLQ inspector is configured. Otherwise it is not exposed and any request is rejected with 503. ## OpenAPI ````yaml /en/openapi/v3-current/ted.yaml get /v1/webhooks/dlq openapi: 3.0.3 info: title: Bank Transfer (TED) Plugin API description: >- Complete API for Brazilian bank transfers (TED OUT, TED IN, P2P) through the Lerian platform, including transfer initiation, processing, status tracking, and cancellation. version: 3.3.1 servers: - url: https://plugin-br-bank-transfer.sandbox.lerian.net description: Sandbox (placeholder — not yet available for public access) security: - BearerAuth: [] tags: - name: Transfers API description: Endpoints for initiating, processing, tracking, and cancelling transfers. - name: Webhooks description: >- Endpoints for registering and managing tenant-scoped webhook subscriptions for transfer events. - name: Webhook DLQ description: Endpoints for inspecting and retrying webhook dead-letter queue messages. - name: Health API description: Endpoints for checking service liveness and readiness. paths: /v1/webhooks/dlq: get: tags: - Webhook DLQ summary: List DLQ Messages description: >- Use this endpoint to list messages currently in the webhook dead-letter queue, scoped to the caller's tenant. The tenant is derived from the bearer JWT (`tenantId` claim), never from a request header. This route is only mounted when authentication is enabled and a DLQ inspector is configured. Otherwise it is not exposed and any request is rejected with 503. operationId: listDLQMessages parameters: - name: limit in: query required: false description: Maximum number of messages to return. schema: type: integer minimum: 1 maximum: 200 default: 50 - name: offset in: query required: false description: Number of messages to skip for pagination. schema: type: integer minimum: 0 default: 0 responses: '200': description: Indicates the DLQ messages page was returned successfully. content: application/json: schema: $ref: '#/components/schemas/DLQListResponse' examples: page: summary: One DLQ message returned value: messages: - messageId: 019c96a0-d1d2-7e3f-4a5b-6c7d8e9f0a1b routingKey: webhook.transfer.completed deathReason: rejected failureReason: HTTP 500 from subscriber tenantId: 11111111-1111-1111-1111-111111111111 transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d eventType: transfer.completed correlationId: 019c96a0-cc10-7abc-d1e2-3f4a5b6c7d8e retryCount: 5 manualRetryCount: 1 timestamp: '2026-02-01T15:35:00-03:00' totalCount: 1 returnedCount: 1 returned: 1 hasNextPage: false hasMore: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: DLQListResponse: type: object required: - messages - totalCount - returnedCount properties: messages: type: array items: $ref: '#/components/schemas/DLQMessage' totalCount: type: integer minimum: 0 description: >- Tenant-filtered message count visited during this scan. When `hasMore` is true this is a best-effort lower bound on the true DLQ depth for this tenant, not the full count. example: 1 returnedCount: type: integer minimum: 0 description: Number of messages in this page after offset and limit are applied. example: 1 returned: type: integer minimum: 0 description: Number of messages returned in this page. example: 1 hasNextPage: type: boolean description: Whether there are more tenant-visible messages beyond this page. example: false hasMore: type: boolean description: >- True when the inspector stopped scanning early after filling the current page. example: false warning: type: string description: >- Set when pagination may be non-deterministic (e.g., concurrent access shifts ordering). example: pagination may be non-deterministic under concurrent access DLQMessage: type: object required: - messageId - routingKey - deathReason - failureReason - tenantId - eventType - retryCount - manualRetryCount - timestamp properties: messageId: type: string description: Unique DLQ message identifier. example: 019c96a0-d1d2-7e3f-4a5b-6c7d8e9f0a1b routingKey: type: string description: Original routing key the message was published with. example: webhook.transfer.completed deathReason: type: string description: >- Reason the broker dead-lettered the message (e.g., `rejected`, `expired`, `maxlen`). example: rejected failureReason: type: string description: >- Last subscriber-side failure detail captured before the message was dead-lettered. example: HTTP 500 from subscriber tenantId: type: string format: uuid description: Tenant that owns the message. example: 11111111-1111-1111-1111-111111111111 transferId: type: string format: uuid description: Transfer ID associated with the webhook event, when present. example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d eventType: type: string description: >- Webhook event type (e.g., `transfer.completed`, `transfer.rejected`). example: transfer.completed correlationId: type: string description: >- Correlation ID propagated from the originating request, when present. example: 019c96a0-cc10-7abc-d1e2-3f4a5b6c7d8e retryCount: type: integer minimum: 0 description: Number of automatic delivery attempts before dead-lettering. example: 5 manualRetryCount: type: integer minimum: 0 description: Number of manual retries already triggered for this message. example: 1 timestamp: type: string format: date-time description: Time the message was dead-lettered. example: '2026-02-01T15:35:00-03:00' ErrorResponse: type: object required: - error properties: error: type: object required: - code - service - category - message - requestId properties: code: type: string description: >- The stable error code. Plugin errors use the `BTF-XXXX` format; JD SPB business/auth rejections pass through the raw vendor code verbatim (e.g. `AAC90`, `ACE95`, `DVE01`), and transport-level JD failures surface the synthetic markers `TRANSPORT` or `JD_MISSING_CODE`. Match on this value rather than on the HTTP status. example: BTF-0010 service: type: string description: The service or domain that produced the error. example: plugin category: type: string description: Machine-readable error category used for retry decisions. enum: - deterministic - transient - rate_limit - plugin example: deterministic message: type: string description: A human-readable error summary. example: >- Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time requestId: type: string description: The request correlation ID. Present even when empty. example: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f fields: type: object additionalProperties: true description: >- Structured validation or retry metadata when available. Field-level, header, path, and query validation details are all returned here. example: currentTime: '2026-02-01T18:30:00-03:00' operatingHours: Mon-Fri 06:30-17:00 UTC-3 responses: BadRequest: description: >- Indicates that the request contains invalid input. Check the field details for specific validation errors. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidInput: summary: Validation error value: error: code: BTF-0001 service: plugin category: deterministic message: >- The request contains invalid fields. Check the field details below. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f fields: recipientIspb: must be 8 digits amount: must be positive Unauthorized: description: Indicates that the request is missing a valid authentication token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Missing authorization value: error: code: BTF-0401 service: plugin category: deterministic message: Missing or invalid authentication token requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f Forbidden: description: >- Indicates that the caller is authenticated but lacks permission for this operation, or the tenant is not licensed for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notLicensed: summary: Tenant not licensed value: error: code: BTF-0403 service: plugin category: deterministic message: Tenant is not licensed to use this endpoint requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f permissionDenied: summary: Caller lacks permission value: error: code: BTF-0405 service: plugin category: deterministic message: Caller lacks permission for this resource requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f InternalServerError: description: Indicates that an unexpected internal error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Internal error value: error: code: BTF-9000 service: plugin category: plugin message: Unexpected error while processing the request requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f ServiceUnavailable: description: >- Indicates that an external service (CRM, JD SPB, Midaz, or Fees) is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: crmUnavailable: summary: CRM service down value: error: code: BTF-0502 service: crm category: transient message: >- Unable to validate account. The CRM service is temporarily unavailable. Try again later. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f jdUnavailable: summary: JD SPB unavailable value: error: code: TRANSPORT service: jd_spb category: transient message: >- Unable to submit transfer. The JD SPB service is temporarily unavailable. Try again later. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f midazUnavailable: summary: Midaz ledger unavailable value: error: code: BTF-2000 service: midaz category: transient message: >- Unable to process transfer. The Midaz ledger service is temporarily unavailable. Try again later. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f feeServiceUnavailable: summary: Fee service unavailable (fail-closed mode) value: error: code: BTF-3000 service: fees category: transient message: >- Unable to calculate fee. The fee service is temporarily unavailable. Try again later. requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f dlqInspectorUnavailable: summary: DLQ inspector not configured value: error: code: BTF-9005 service: plugin category: deterministic message: DLQ inspector is not configured requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token authentication. The tenantId is derived from the bearer token or authenticated request context and is not supplied through X-Organization-Id. ````