references/queues/gotchas.md
Queues Gotchas & Troubleshooting
Fetch the linked documentation before changing retry policy or interpreting delivery behavior.
| Symptom or question | Documentation and decision | |---------------------|----------------------------| | Successful work repeats after another message fails | Read acknowledgement and retry rules; use per-message outcomes for independent work. | | A caught failure disappears instead of retrying | Read handler lifecycle and APIs; returning successfully can acknowledge messages. Explicitly retry failed work when continuing. | | Duplicate processing | Read delivery guarantees; enforce idempotency at the side-effect destination. | | Pull consumers cannot decode payloads | Check pull consumer encoding and content types against the producer. | | Messages stop arriving or backlog grows | Check consumer configuration, pause state, and queue metrics. | | Dead-letter volume rises or messages disappear after retries | Read Dead Letter Queues; inspect failures and plan recovery before increasing retries. | | API errors, resource exhaustion, or CPU failures | Read error codes, limits, and consumer concurrency. | | Retention, delay, throughput, or cost assumptions no longer hold | Retrieve current limits and pricing for the account's plan. |
Distinguish transient dependency failures from invalid payloads before choosing retry or recovery behavior. Acknowledging a failed message does not send it to a dead-letter queue. If handling a permanent failure separately, persist the intended recovery record successfully before acknowledging; use the documented dead-letter policy when relying on retry exhaustion.
See patterns.md for idempotency and downstream integration decisions.