## TL;DR
Honor the API's Retry-After response, back off exponentially with jitter, and checkpoint after every file so a rerun resumes instead of restarting. The pass died because it retried immediately at full speed, which just burns quota faster. Backoff plus checkpoints turns a rate limit into a slowdown instead of a failure.

```text
docs agent failed after hitting translation api rate limit mid localization pass
```

## Steps
1. Confirm it is a rate limit: check the translation step logs for 429 status codes or quota-exceeded messages. Expected: the errors cluster at high request rates, not on specific content.
2. Add retry with backoff: on a 429, wait the number of seconds from the Retry-After header (or double the wait each attempt, with jitter) before retrying, up to a sane max. Expected: a throttled run completes slowly instead of aborting.
3. Lower the request rate: batch multiple strings per API call and reduce concurrency until the 429s stop. Expected: steady throughput with no 429s in the log.
4. Checkpoint progress: record each completed file and locale (a small JSON state file works) and skip completed ones on rerun. Expected: killing and restarting the pass resumes where it stopped.
5. Rerun the localization pass and verify every locale has every file translated. Expected: no missing translations and no 429s in the final log.

## Use this when
- the translation step fails with 429 or quota errors mid-pass
- some locales are translated and others are missing after a run
- rerunning the pass restarts from zero and hits the limit again

## Not for this skill when
- translations are wrong but complete (quality problem, not a limit problem)
- the API rejects the content itself (validation error, not 429)
- you hit a hard monthly quota cap (backoff cannot help; you need a higher quota or fewer strings)

## Variant phrasings
- translation API 429 during docs localization
- docs agent throttled mid translation pass
- localization pass died on rate limit

## Why it happens
Translation APIs price by throughput: bursts of parallel requests trip per-minute quotas, and naive retry loops re-fire immediately, which the API counts as more load. Without backoff the agent effectively hammers its own quota, and without checkpoints every retry restarts the burn from zero.

## Edge cases
- Retry-After can be minutes long: cap total wait time and surface a clear "paused for quota" status instead of hanging silently.
- Batching too aggressively can hit per-request size limits: find the sweet spot between batch size and request count.
- Machine-translated output still needs a quality spot-check: rate limits do not excuse shipping bad translations.
- Some APIs count characters, not requests: monitor both dimensions.

## Provenance

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