# 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

```text
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

```bash
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

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

Expected: You find the hot loop to pace.

### Step 3: Checkpoint each completed translation

```bash
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

```bash
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