locale agent hit deepl rate limit mid batch translation and the sync failed

Fix the locale agent hitting the DeepL rate limit mid batch

TL;DR

The batch outruns DeepL's rate limit, so throttle the agent and resume from where it stopped. DeepL limits requests per second, and a fast loop trips it partway through. Add a delay between calls, checkpoint completed items, and rerun to finish the remainder.

The error

Locale agent: DeepL 429 Too Many Requests at item 1,240 of 4,000
batch translation sync failed halfway

Fix it

Step 1: Confirm it is rate limiting not quota

node -e "console.log('429 with retry-after means rate limit, 456 means quota -- check which you got')"

Expected: You know which limit you hit.

Step 2: Add pacing between requests

grep -n "await translate" scripts/batch-translate.js | head -3

Expected: You find the hot loop to pace.

Step 3: Checkpoint each completed translation

node -e "console.log('pattern: write results incrementally, on restart skip items already translated')"

Expected: A rerun resumes instead of restarting.

Step 4: Rerun to complete the batch

node scripts/batch-translate.js | tail -3

Expected: The remaining items translate without 429s.

When to use this

• A locale agent hits DeepL 429 mid batch
• Batch translation dies partway

When NOT to use this

• The error is 456, that is quota, different fix
• The error is 403, that is auth

Tool and version compatibility

• DeepL API rate limits, batch translation agents
• Checkpointed batch runners

Variant phrasings

rate limit on the free tier is tighter

Pace more aggressively there, or move batch workloads to pro.

429s even at low speed

Something else is using the same credential. Check for parallel jobs sharing the key.

Why it happens

DeepL throttles request rate separately from the character quota. A tight loop with no pacing exhausts the per-second budget, and the 429 stops the batch wherever it happens to be.

Edge cases

• Honor retry-after when present, it is the server telling you the exact wait
• Batch multiple texts per request where the API allows, fewer requests total
• Jitter the pacing so parallel workers do not synchronize into waves

Provenance

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