Discard a message

Last updated Oct 2, 2026

POST /spools/{spool}/discard

Drops the message permanently — the token names it; the payload is unrecoverable once discarded. The one operation that takes either kind of token, exactly one per call: the lease from a receive (a consumer's terminal drop — the message is gone and counted as discarded, not acked; park it with fail instead when someone should look at it first), the handle from a listing, or the handle from a send to cancel the message before its first delivery (410 once anything has moved it).

Sample

curl -X POST "$SPOOLER_API/spools/<spool>/discard" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  -H "Spooler-Lease: <lease>"

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–63 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
Spooler-Lease	header	Lease, 16–256 chars, ^[A-Za-z0-9_-]+$	no	The lease from a receive, presented back; exactly one of Spooler-Lease and Spooler-Handle.
Spooler-Handle	header	Handle, 16–256 chars, ^[A-Za-z0-9_-]+$	no	The handle from a listing or from a send, presented back; exactly one of Spooler-Lease and Spooler-Handle.

Responses

Status	Description
204	Discarded.
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.
410	The lease no longer settles anything: expired, already settled, or predates a primary change.
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.
500	The server failed; kind operation_unconfirmed means the write was accepted but its durability is unknown.
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.