Retry Queue

The retry queue handles conversions that fail because the GCLID is too new for Google Ads to recognize. Google Ads can take several hours to process new ad clicks. During this window, conversion uploads return a CLICK_NOT_FOUND error. The retry queue automatically re-attempts these uploads until the GCLID becomes available or the TTL expires.

How It Works

Queueing

When a conversion upload fails with CLICK_NOT_FOUND:

1. The conversion is added to the retry_queue table with type gads_click_not_found and status pending.
2. The retry_after timestamp is set to 30 minutes in the future.
3. The max_attempts is calculated from the configured Retry TTL (default 12 hours, retrying every ~30 min = ~24 attempts).
4. A conversion log entry is created with status queued.
5. The webhook returns HTTP 200 with { success: true, queued: true }.

Processing

A cron job runs every 5 minutes and processes pending queue items:

1. The cron handler queries for up to 10 items where status = 'pending' and retry_after has passed.
2. Each item is marked as processing.
3. The system checks if the Retry TTL has been exceeded. If so, the item is marked as failed.
4. Otherwise, the Google Ads token is refreshed and the conversion is re-attempted via uploadClickConversions.
5. On success, the item is marked as completed and a success entry is written to the conversion log.
6. On failure, the item is rescheduled with retry_after set 30 minutes in the future.

Retry Limits

Each queue item tracks attempt_count against max_attempts. Once the maximum is reached, the item remains in failed status and is not retried automatically. Additionally, if the configured Retry TTL (hours since the item was first created) has been exceeded, the item fails immediately without attempting the upload.

Configuration

Retry TTL (hours)

The retry TTL is configurable in Settings > Google Ads under the global settings section. The value is specified in hours.

Queue Management

The retry queue can be monitored and managed in Settings > Queues:

• View pending and failed items with their scheduled retry times and attempt counts.
• Reprocess Selected – Reset failed items to pending status to force a retry on the next cron cycle.
• Remove Selected – Permanently delete items that should not be retried.

Queue Item Lifecycle

pending  -->  processing  -->  completed
                  |
                  v
               failed  -->  (reprocess)  -->  pending
                  |
                  v
          (max attempts or TTL expired -- stays failed)