9 AMQP Delivery: Guarantees and Acknowledgements

9.6.1 AMQP Message Format

Inspect Figure 9.1 before assigning application fields so transport controls and business payload do not become mixed together.

Read Figure 9.1 from header to properties to body. Delivery controls such as durability and priority belong in the header; identifiers and content description travel as properties; the application value remains in the body. That separation supports routing, correlation, and payload evolution without redefining the whole envelope.

9.6.2 Header Section

The header contains delivery-related metadata:

Example: Setting persistent, high-priority message:

import pika

properties = pika.BasicProperties(
    delivery_mode=2,  # Persistent (survives restart)
    priority=8,       # High priority (0-9 scale)
    expiration='60000'  # TTL: 60 seconds
)

channel.basic_publish(
    exchange='orders',
    routing_key='order.priority',
    body='{"order_id": 12345}',
    properties=properties
)

9.6.3 Properties Section

Properties provide message metadata for routing and processing:

Example: Complete message with properties:

properties = pika.BasicProperties(
    content_type='application/json',
    content_encoding='utf-8',
    message_id=str(uuid.uuid4()),
    correlation_id=request_correlation_id,
    reply_to='response_queue',
    timestamp=int(time.time()),
    type='sensor.temperature',
    app_id='weather-station-01',
    delivery_mode=2
)

9.6.4 Body Section

The body contains the actual message payload:

First: Can be binary or text

Next: Encoding specified in properties

Then: No size limit (but broker may impose limits)

After that: Common formats: JSON, Protocol Buffers, MessagePack

9.7.1 Three Delivery Modes

Before selecting a delivery mode, inspect the loss, duplicate, and coordination boundaries in Figure 9.2.

Read Figure 9.2 from at-most-once to at-least-once and then the exactly-once intent. Acknowledgment and retry trade possible loss for possible duplication; stronger coordination costs more state. The final caveat returns the design to application idempotency because transport evidence alone cannot prove a business effect happened exactly once.

9.7.2 1. At-Most-Once (0 or 1)

Message delivered once or not at all. Fastest but may lose messages.

Characteristics:

First: No acknowledgment required

Next: Fastest, lowest overhead

Then: Fire-and-forget pattern

Implementation:

# Producer: No confirms
channel.basic_publish(
    exchange='sensors',
    routing_key='temperature',
    body='22.5',
    properties=pika.BasicProperties(delivery_mode=1)  # Transient
)

# Consumer: Auto-acknowledge
channel.basic_consume(
    queue='sensor_data',
    on_message_callback=callback,
    auto_ack=True  # Message removed immediately on delivery
)

Use cases:

After that: Non-critical telemetry

Also inspect: Sensor readings where occasional loss is acceptable

Finally: High-throughput streaming where speed matters more than completeness

9.7.3 2. At-Least-Once (1 or more)

Message guaranteed to be delivered, but may arrive multiple times.

Characteristics:

First: Requires acknowledgment

Next: Retries on failure

Then: Possible duplicates (consumer must handle)

Implementation:

# Producer: With confirms
channel.confirm_delivery()

try:
    channel.basic_publish(
        exchange='orders',
        routing_key='order.created',
        body=json.dumps(order),
        properties=pika.BasicProperties(
            delivery_mode=2,  # Persistent
            message_id=str(uuid.uuid4())
        )
    )
except pika.exceptions.UnroutableError:
    # Handle unroutable message
    retry_or_log(order)

# Consumer: Manual acknowledgment
def callback(ch, method, properties, body):
    try:
        process_order(body)
        ch.basic_ack(delivery_tag=method.delivery_tag)
    except Exception:
        ch.basic_nack(delivery_tag=method.delivery_tag, requeue=True)

channel.basic_consume(
    queue='orders',
    on_message_callback=callback,
    auto_ack=False  # Manual ACK required
)

Use cases:

After that: Important events and commands

Also inspect: Order processing (with idempotent handlers)

Finally: Notifications that must be delivered

9.7.4 3. Exactly-Once (exactly 1)

Message delivered exactly once with no loss or duplicates.

Characteristics:

First: Uses transactions or deduplication

Next: Highest reliability, highest overhead

Then: Most complex to implement

Implementation (transaction-based):

# Producer: Transactional publishing
channel.tx_select()
try:
    channel.basic_publish(
        exchange='payments',
        routing_key='payment.process',
        body=json.dumps(payment),
        properties=pika.BasicProperties(delivery_mode=2)
    )
    channel.tx_commit()
except Exception:
    channel.tx_rollback()
    raise

# Consumer: With deduplication
def callback(ch, method, properties, body):
    message_id = properties.message_id

    # Check if already processed
    if redis.exists(f'processed:{message_id}'):
        ch.basic_ack(delivery_tag=method.delivery_tag)
        return

    try:
        result = process_payment(body)
        redis.setex(f'processed:{message_id}', 86400, '1')  # 24h TTL
        ch.basic_ack(delivery_tag=method.delivery_tag)
    except Exception:
        ch.basic_nack(delivery_tag=method.delivery_tag, requeue=True)

Use cases:

After that: Financial transactions

Also inspect: Critical commands that cannot be duplicated

Finally: Billing and accounting events

Checkpoint: Delivery Promise

You now know:

• At-most-once is fastest because it uses no acknowledgment, but messages may be lost.
• At-least-once adds ACKs and retries, so consumers need duplicate handling such as message-ID.
• Exactly-once uses transactions or deduplication when duplicates are worse than the overhead.

9.9.1 ACK Types

9.9.2 Prefetch Count

Prefetch controls how many unacknowledged messages a consumer can hold.

Read prefetch as a bounded in-flight window, not a universal speed setting. Start with handler duration and round-trip overhead, then check fairness across consumers and the redelivery burst after a crash. Raise the value only when measured idle time shows that additional overlap improves throughput without hiding too much unfinished work in one process.

# Limit to 1 unacknowledged message at a time
channel.basic_qos(prefetch_count=1)

# Best for:
# - Long-running tasks (prevents one consumer hoarding all work)
# - Fair distribution across multiple consumers

Prefetch recommendations:

Checkpoint: Acknowledgments and Prefetch

You now know:

• A positive ACK removes the message; a NACK can requeue it or dead-letter it.
• prefetch_count=1 is fair for long-running tasks because one consumer cannot hoard work.
• Faster work can use 50-100 under 100 ms, 10-20 for 100 ms to 1 s, and 1-5 for 1 s to 10 s.

9.10.1 DLQ Triggers

Messages are sent to DLQ when:

First: Consumer rejects with requeue=false: basic_nack(requeue=False)

Next: Message TTL expires: Message exceeded time-to-live

Then: Queue length exceeded: Queue reached maximum length

After that: Message rejected after max retries: Application-level retry exhaustion

9.10.2 DLQ Configuration

# Declare dead letter exchange
channel.exchange_declare(
    exchange='dlx',
    exchange_type='direct'
)

# Declare dead letter queue
channel.queue_declare(queue='dead_letters')
channel.queue_bind(queue='dead_letters', exchange='dlx', routing_key='failed')

# Declare main queue with DLQ configuration
channel.queue_declare(
    queue='orders',
    arguments={
        'x-dead-letter-exchange': 'dlx',
        'x-dead-letter-routing-key': 'failed',
        'x-message-ttl': 300000  # Optional: 5 min TTL
    }
)