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

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.

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/pstxRaA8Xs7actGG19VqJiIA