Peek the oldest failed message

Last updated Aug 20, 2026

GET /spools/{spool}/queues/{queue}/failures/head

Reads the head of the failure queue without consuming it: repeated reads return the same message until it is recovered or discarded. The Spooler-Lease header carries the lease that recover and discard present back. Responses carry Cache-Control no-store.

Sample

curl -X GET "$SPOOLER_API/spools/<spool>/queues/<queue>/failures/head" \
  -H "Authorization: Bearer $SPOOLER_KEY"

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.

Responses

Status	Description
200	The oldest failed message.
204	The failure queue is empty.
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.
429	The per-account request rate cap is exceeded; retry after the Retry-After delay.
503	The spool is momentarily unavailable.

200 headers

Header	Description
Spooler-Lease	Present back to recover or discard.
Spooler-Message-Id	The message's id.
Spooler-Retry-Count	Redeliveries before the message failed.

429 headers

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