## TL;DR
A 429 is a pause button, not a failure. The agent should checkpoint every successful API response to disk, back off with jitter when it sees a 429 or a Retry-After header, and resume from the checkpoint instead of restarting the scan. Rate limits are expected; losing the scan to one is the bug.

```text
recon agent hit API rate limit mid-scan and its scan failed on authorized target
```

## Use this when
- The recon agent calls an external data API (WHOIS/RDAP providers, enrichment services, subdomain feeds) and the scan dies on HTTP 429.
- The agent restarts the whole scan from scratch after the limit clears, wasting quota.
- The failure happens mid-scan with partial results already collected.

## Not for this skill when
- The rate limit comes from the authorized target's own application. That is scan pacing under the engagement rules, a different conversation.
- The API key is invalid or revoked. That is an authentication failure, not throttling.
- The scan has no external API calls at all. Then a 429 cannot be the cause.

## Steps
1. Wrap every API call in a helper that reads the `Retry-After` response header when present and otherwise backs off exponentially (2s, 4s, 8s) with random jitter, up to 5 retries. Verify: a forced 429 in testing triggers a wait, not an exception.
2. Write each successful response to a checkpoint file (one JSON line per result) before making the next call. Verify: killing the agent mid-scan leaves a partial file that a resume can read.
3. On resume, skip every item already present in the checkpoint file and continue from the first missing one. Verify: the resumed run makes no duplicate API calls.
4. Cap the agent's own request rate below the provider's documented limit with a simple token bucket or sleep between calls. Verify: a 10-minute test run stays under the quota without hitting 429.
5. Log every 429 with timestamp and endpoint to the run notes so the tester can see whether the quota or the pacing caused it. Verify: the notes distinguish throttled calls from failed ones.

## Variant phrasings
### agent scan died on 429 from data API
Short symptom phrasing.
### recon agent loses progress on API throttling
Checkpoint-focused variant.
### external API rate limit killed the recon run
Provider-side phrasing.

Compatibility: any HTTP client. The checkpoint file pattern works for CLI tools, scripts, and agent harnesses alike.

## Why it happens
Most recon agents are written for the happy path: call the API in a loop until the list is done. Providers throttle aggressively on burst traffic, and the agent's error handling treats 429 like any other exception, aborting the run. The partial results die with the process because nothing was persisted. Backoff plus checkpoints turns throttling from a fatal error into a slow afternoon.

## Edge cases / pitfalls
- Honor `Retry-After` exactly; hammering through a provider's stated wait is how temporary limits become account suspensions.
- Checkpoint files can hold sensitive target data. Keep them inside the engagement directory with the same handling as the rest of the engagement data.

## Provenance

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