---
title: "Defer a message to be retried"
method: POST
path: "/v1/queue.defer"
tags: ["Querator V1"]
---

# Defer a message to be retried

`POST /v1/queue.defer`

Defer an item to be processed again at a later date/time. Once the `enqueue_at` time is reached, querator will enqueue this item into the specified queue and the `attempted` counter for this item will increment by 1. 

If the item should not be retried, but failed immediately. Set `dead: true` and the item will be placed in the dead letter queue regardless of the number of attempts left on the message.

If you wish to fail a message such that it is deleted from the queue and never offered to another consumer, nor placed into the dead letter queue, then call `/queue.complete` instead.

## Request body

- QueueDeferRequest
  - `queue_name` string, required — The queue name provided when the item was reserved. If the `queue_name` does not match the original `queue_name` provided when the item was reserved, then the defer request will return a non 200 status code.
  - `partition` integer, required — The partition provided when the item was reserved. If the `partition` does not match the original `partition` provided when the item was reserved, then the defer request will return a non 200 status code.
  - `items` QueueDeferItem[], required
    - `id` string, required — The item id provided when the message was reserved. If the item id provided does not match an item id already in `reserve` status, then the defer request will return a non 200 status code.
    - `enqueue_at` string, date-time, required — The timestamp after which the message will be queued to the queue/partition specified. If `offer_at` is empty the item will be immediately re-added to the queue and the attempts counter incremented.
    - `dead` boolean, required — Indicates the item is dead, will not be retried regardless of the number of attempts remaining. If set to `true` the defer will place the item in the dead letter queue for the specified queue.

## Response `200`

- QueueDeferResponse
  - `code` integer, required — The response code
  - `code_text` string — The text explaination of the code
  - `message` string — The message that contains details explaining the reason for the code

## Changes

- **2024-09-16** `22a36c374092` — 3 breaking, 3 info
  - added the new required request property `items`
  - added the new required request property `partition`
  - added the new required request property `queue_name`
  - added the optional property `code_text` to the response with the `200` status
  - …2 more
- **2024-09-15** `ba3240950bb2` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kapetan-io/apis/querator-api/changes/v1/queue.defer/post.md)

---

[API](https://skmtc.dev/kapetan-io/apis/querator-api.md) · [All operations](https://skmtc.dev/kapetan-io/apis/querator-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kapetan-io/querator-api/revisions/36fb0df413ee/schema)