ReceiveDeadLetterQueueRecords
Receives up to 10 dead-letter records from the specified queue. Each queue has built-in
dead-letter handling: when a record has been received MaxReceiveCount times
without being acknowledged, it becomes a dead-letter record, which usually means your queue
consumer could not process it. The dead-letter record stays in the same queue, and
ReceiveQueueRecords no longer returns it.
Dead-letter records carry the same data and partition key as when they were first delivered, and are returned with a receipt handle. Use the receipt handle to acknowledge the record with AcknowledgeDeadLetterQueueRecords, which discards it, to change its visibility with UpdateDeadLetterQueueRecordsVisibility, or to restore it with RestoreDeadLetterQueueRecords, which returns it to the normal receive path so that ReceiveQueueRecords can return it again.
Use this operation to inspect the records your queue consumer could not process, so you can correct the cause and then either acknowledge or restore them.
A queue delivers dead-letter records while it is in the ACTIVE
state.
Request Syntax
{
"Limit": number,
"QueueARN": "string",
"VisibilityTimeoutSeconds": number,
"WaitTimeSeconds": number
}
Request Parameters
The request accepts the following data in JSON format.
- Limit
-
The maximum number of records to return. The queue never returns more dead-letter records than this value, and might return fewer. The default is 10.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10.
Required: No
- QueueARN
-
The ARN of the queue whose dead-letter records are received.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
arn:aws.*:kinesis:.*:\d{12}:queue/\S+Required: Yes
- VisibilityTimeoutSeconds
-
The duration, in seconds, that the records returned by this request are in flight and not visible to any consumer instance. If you do not specify this value, the queue's visibility timeout is used.
Type: Integer
Valid Range: Minimum value of 0. Maximum value of 43200.
Required: No
- WaitTimeSeconds
-
The duration, in seconds, that the call waits for a record to become visible before returning. The default is 9.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 20.
Required: No
Response Syntax
{
"QueueRecords": [
{
"ApproximateArrivalTimestamp": number,
"Data": blob,
"FirstReceiveTimestamp": number,
"PartitionKey": "string",
"ReceiptHandle": "string",
"ReceiveCount": number,
"RecordId": "string"
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- QueueRecords
-
The dead-letter records received from the queue. This list is empty when no dead-letter records are visible.
Type: Array of QueueRecord objects
Errors
For information about the errors that are common to all actions, see Common Error Types.
- AccessDeniedException
-
Specifies that you do not have the permissions required to perform this operation.
HTTP Status Code: 400
- InternalFailureException
-
The processing of the request failed because of an unknown error, exception, or failure.
HTTP Status Code: 500
- InvalidArgumentException
-
A specified parameter exceeds its restrictions, is not supported, or can't be used. For more information, see the returned message.
- message
-
A message that provides information about the error.
HTTP Status Code: 400
- KMSAccessDeniedException
-
The ciphertext references a key that doesn't exist or that you don't have access to.
- message
-
A message that provides information about the error.
HTTP Status Code: 400
- KMSDisabledException
-
The request was rejected because the specified KMS key isn't enabled.
- message
-
A message that provides information about the error.
HTTP Status Code: 400
- KMSInvalidStateException
-
The request was rejected because the state of the specified resource isn't valid for this request. For more information, see How Key State Affects Use of a Customer Master Key in the AWS Key Management Service Developer Guide.
- message
-
A message that provides information about the error.
HTTP Status Code: 400
- KMSNotFoundException
-
The request was rejected because the specified entity or resource can't be found.
- message
-
A message that provides information about the error.
HTTP Status Code: 400
- KMSOptInRequired
-
The AWS access key ID needs a subscription for the service.
- message
-
A message that provides information about the error.
HTTP Status Code: 400
- KMSThrottlingException
-
The request was denied due to request throttling. For more information about throttling, see Limits in the AWS Key Management Service Developer Guide.
- message
-
A message that provides information about the error.
HTTP Status Code: 400
- ResourceNotFoundException
-
The requested resource could not be found. The stream might not be specified correctly.
- message
-
A message that provides information about the error.
HTTP Status Code: 400
- ThrottlingException
-
The request was denied because the request rate is too high. Reduce the frequency of your requests, and retry them with exponential backoff.
- message
-
A message that provides information about the error.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: