## TL;DR
Slow down and make the backfill resumable: track which tables have been checked in a state file, respect the API's rate limit headers with real backoff, and resume from the first unchecked table instead of restarting. A tight loop over hundreds of tables trips the limit partway, and a restart from zero guarantees it trips again at the same place.

```text
when agent tried to backfill freshness check agent triggered rate limit error failed
```

## Use this when
- The check or run fails with this symptom: an agent backfill of freshness checks triggered a rate limit error.
- You are working on an agent backfilling freshness checks across many tables and the failure repeats on the same data or configuration.
- You need the failing rows, rule, or stage isolated before changing thresholds or code.

## Not for this skill when
- A single-table freshness call that is rate limited because another job shares the quota, where the fix is coordination rather than backoff tuning.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Write per-table progress to a state file as each check completes, before starting the next table. Verify: completed tables are recorded incrementally
2. Read the rate limit and retry headers on responses and pace requests under the stated limit with exponential backoff on 429 responses. Verify: request pacing follows the API's stated limits
3. On a rate limit error, stop the run cleanly and record the next unchecked table as the resume point. Verify: the run ends with a named resume point instead of a partial mystery
4. Resume from the state file and confirm the backfill completes without re-checking finished tables. Verify: the resumed run finishes the remaining tables only

## Variant phrasings
### agent freshness backfill rate limit error
The backfill-limit phrasing.
### 429 while agent checking freshness many tables
The status-code phrasing.
### freshness check loop throttled api agent
The throttling phrasing.

Compatibility: Agents calling freshness APIs in Soda, Monte Carlo, or warehouse metadata endpoints

## Why it happens
Bulk backfills turn a per-call limit into a when, not an if: hundreds of rapid calls exhaust the quota mid-run. Without progress state, the agent cannot tell checked from unchecked tables, so retries duplicate work and hit the same wall.

## Edge cases / pitfalls
- Share one pacing limiter across parallel agent workers; per-worker limits still sum past the API quota.
- Freshness results change slowly; caching results for an hour rarely harms a backfill's usefulness.

## Provenance

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