Update queue settings

Last updated Oct 2, 2026

PATCH /spools/{spool}/queues/{queue}

Replaces the provided settings on the queue; omitted fields keep their current values. A draining queue still accepts updates — its settings keep governing the remaining consumers; only a queue whose deletion is completing fails with 409.

Sample

curl -X PATCH "$SPOOLER_API/spools/<spool>/queues/<queue>" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  -H "Content-Type: application/json" \
  --data '{"leaseTimeoutSeconds": <leaseTimeoutSeconds>}'

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–63 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
queue	path	IdentName, 1–63 chars, ^[A-Za-z0-9_:-]+$	yes	The queue name.

Request body

Required; application/json.

Settings to replace on the queue; omitted fields keep their current values. At least one field must be present.

The shape, not a sample: values are the wire types; ? marks an optional field.

{
  // Seconds to wait before an unacked delivery is auto-nacked; 0 disables
  // the timeout, at most a year. Applies to leases taken after the
  // update.
  //
  // Range: 0–31,536,000
  leaseTimeoutSeconds?: integer,

  // Redeliveries before a message is failed; 0 means no retries.
  //
  // Range: 0–65,535
  maxRetries?: integer,

  // Seconds a dedup key is remembered for deduplication, at most five
  // minutes. 0 disables dedup. A new value forgets every remembered key
  // at once; the current value changes nothing.
  //
  // Range: 0–300
  dedupWindowSeconds?: integer,

  // Seconds a message is kept before it is discarded, counted as
  // effectiveRetentionSeconds describes; at least a minute, at most the
  // plan's retention limit.
  //
  // Range: ≥ 60
  retentionSeconds?: integer,

  // Caps the rate Recv hands out messages. The zero value (both fields 0)
  // removes the limit.
  recvRateLimit?: {
    // The token-bucket refill interval in microseconds; at least 10000
    // (10ms) when setting a limit, or 0 together with burst 0 to remove
    // it.
    //
    // Range: ≥ 0
    intervalMicros: integer,

    // The bucket size; at least 1 when setting a limit, or 0 together
    // with intervalMicros 0 to remove it.
    //
    // Range: 0–2,147,483,647
    burst: integer,
  },
}

Responses

Status	Description
204	Updated.
400	The request is malformed; the kind names the problem.
401	The API key is missing or not recognized.
402	The account is suspended.
403	A plan limit refuses the operation; the kind names it. A 403 without a kind, on any operation, means the API key is blocked.
404	The spool or queue does not exist; the kind says which.
409	Concurrent state refuses the operation; the kind names it.
429	The per-account request rate cap is exceeded. The body names the kind (rate_limited); the wait is the Retry-After header and is not repeated in the body. Headers are as structured as the body, and this one is the header HTTP defines for a wait.
503	The spool is momentarily unavailable.

429 headers

Header	Description
Retry-After	Seconds until the next request is admitted, whole and at least 1; always the delay-seconds form, never an HTTP-date.