## TL;DR

Merging 500 pairs fires hundreds of write calls in a burst, which trips the rate limiter mid-run and leaves half the pairs unmerged. Put merges in a queue, pace them under the limit, and record each completed merge so a rerun skips it. Merges must be resumable, not all-or-nothing.

## Error

```text
{
  "status": "error",
  "message": "You have reached your daily limit",
  "errorType": "RATE_LIMIT"
}
```

## Steps

1. Stop the burst loop. Move the 500 pairs into a persistent queue (file or table) with a status per pair. Expected: the work is durable and visible.
2. Process the queue at a paced rate (for example, one merge every few seconds, watching rate-limit headers). Expected: no 429s.
3. Mark each pair merged immediately after success. Expected: reruns skip completed pairs.
4. On a 429, back off using the Retry-After header and resume the queue. Expected: the run survives limits.
5. Verify the final state: every pair merged or explicitly failed with a reason. Expected: no silent skips.

## When to use

- Merge loops hit rate limits partway.
- An agent merges in a tight loop with no pacing.
- After a 429, the run's merge state is unknown.

## When not to use

- Salesforce REQUEST_LIMIT_EXCEEDED (different limits).
- Merge failures from data errors (fix the pair, not the pacing).

## Tool compatibility

- HubSpot merge endpoints; rate-limit headers.
- Any queue (file, database, task queue).

## Variant phrasings

### 429 mid-merge

Queue, pace, and resume.

### half the pairs unmerged after limit

The queue ledger tells you which half.

## Why it happens

Merges are write-heavy and agents loop them as fast as possible. The rate limiter does not care that the work is legitimate; it only sees the burst.

## Edge cases

- Merging is not always idempotent; re-merging an already-merged pair can error, so the ledger matters.
- Daily limits need multi-day scheduling for very large dedupe backlogs.
- Failed merges need a dead-letter list with reasons, not silent drops.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SeLjAcgsZAiMjCB7AmYs8A