REST API · dlq

GET /dlq/by-request/{requestId}

Every currently retained DLQ row for one inbound request. One request can fan out to multiple targets and can have more than one retained row for the same target, so `entries` is always a stream-row list.

get_api_dlq_get_by_request

Authentication

• Bearer

Parameters

Responses

200

Every retained dead-letter entry for one request.

application/json

{
    "properties": {
        "requestId": {
            "type": "string",
            "format": "uuid"
        },
        "entries": {
            "type": "array",
            "items": {
                "properties": {
                    "id": {
                        "description": "Dead-letter entry id, of the form `{ms}-{seq}`. Changes whenever the entry is replayed and dead-letters again; prefer `requestId` to follow one request across replays.",
                        "type": "string"
                    },
                    "requestId": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "targetId": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "failureCode": {
                        "description": "Stable machine-readable cause of the failure. `unclassified` for an entry written before codes existed.",
                        "type": "string",
                        "enum": [
                            "target_rejected",
                            "invalid_target_url",
                            "signing_failed",
                            "egress_refused",
                            "retries_exhausted",
                            "credential_destination_mismatch",
                            "credential_project_mismatch",
                            "credential_service_unavailable",
                            "credential_unavailable",
                            "contract_version_unsupported",
                            "undecodable_entry",
                            "internal",
                            "unclassified"
                        ]
                    }
                },
                "type": "object"
            }
        }
    },
    "type": "object"
}

{
    "requestId": "a1b2c3d4-5e6f-4a1b-8c2d-9e0f1a2b3c4d",
    "entries": [
        {
            "id": "1768464000123-0",
            "requestId": "a1b2c3d4-5e6f-4a1b-8c2d-9e0f1a2b3c4d",
            "targetId": "b2c3d4e5-6f7a-4b2c-8d3e-0f1a2b3c4d5e",
            "configVersion": 7,
            "failureReason": "maxRetriesExhausted: http503",
            "failureCode": "retries_exhausted",
            "failedAttempts": "3",
            "failedAt": "1768464300000",
            "payload": "{\"event\":\"lifecycle.updated\"}"
        }
    ]
}

404

No DLQ entry found for this requestId.

application/json

{
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "description": "Machine-readable error code, e.g. \"not_found\", \"forbidden\", \"validation\".",
            "type": "string",
            "enum": [
                "bad_request",
                "unauthorized",
                "insufficient_credits",
                "forbidden",
                "web_only",
                "allowlist_widens",
                "not_found",
                "conflict",
                "draft_revision_conflict",
                "rollback_confirmation_conflict",
                "not_replayable",
                "targets_outside_allowlist",
                "gone",
                "deprecated_operation",
                "validation",
                "rate_limited",
                "payment_provider",
                "verification_unavailable",
                "analytics_unavailable",
                "credential_vault_unavailable",
                "notification_grants_unavailable"
            ]
        },
        "message": {
            "description": "Human-readable explanation of what went wrong. Absent on a field-level validation failure, where `fields` carries the detail instead.",
            "type": "string"
        },
        "object": {
            "description": "The resource the error concerns, when there is one.",
            "required": [
                "type",
                "id"
            ],
            "properties": {
                "type": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                }
            },
            "type": "object"
        },
        "action": {
            "description": "What to do next, naming the call or the panel page that does it. Absent when there is no corrective step.",
            "type": "string"
        },
        "fields": {
            "description": "Present when `error` is \"validation\" — one message per rejected field, keyed by the field name.",
            "type": "object",
            "additionalProperties": {
                "type": "string"
            }
        },
        "retry_after": {
            "description": "An RFC 3339 timestamp, the moment the request may be retried. Not every `rate_limited` refusal carries one.",
            "type": "string",
            "format": "date-time"
        }
    },
    "type": "object"
}