Update queue settings

Last updated Aug 20, 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 '{}'

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–64 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
queue	path	IdentName, 1–64 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.

Field	Type	Required	Description
leaseTimeoutSeconds	integer, 0–31,536,000	no	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.
maxRetries	integer, 0–65,535	no	Redeliveries before a message lands in the failure queue; 0 means no retries.
dedupWindowSeconds	integer, 0–300	no	Seconds a dedup key is remembered for deduplication, at most five minutes. 0 disables dedup.
retentionSeconds	integer, ≥ 60	no	Seconds a message is kept before it is discarded; at least a minute, at most the plan's retention limit.
recvRateLimit	RateLimitUpdate	no	Caps the rate Recv hands out messages. The zero value (both fields 0) removes the limit.

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.
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; retry after the Retry-After delay.
503	The spool is momentarily unavailable.

429 headers

Header	Description
Retry-After	Seconds until the next request is admitted.