translation agent failed retrying crowdin upload after api error

Fix the translation agent failing to retry a Crowdin upload after an API error

TL;DR

The agent gives up after the first API error, so wrap the upload in retries with backoff. Transient Crowdin errors, 429s and 5xx, clear on retry, but the agent treats them as fatal. Retry retryable statuses a few times with growing delays, and only fail on 4xx that will never succeed.

The error

Translation agent: Crowdin upload failed after 1 attempt
API returned 503, agent aborted the whole sync

Fix it

Step 1: Classify which errors deserve a retry

node -e "console.log('retry: 429, 500, 502, 503, 504 and network errors. do not retry: 400, 401, 403, 404, 409, 422')"

Expected: You have a retryable list.

Step 2: Wrap the upload call with backoff

grep -n "upload" scripts/translate-agent.js | head -5

Expected: You find the call to wrap.

Step 3: Implement 3 retries with exponential delay

node -e "console.log('pattern: for attempt in 1..3: try upload, on retryable error sleep 2^attempt seconds, else throw')"

Expected: Transient errors get absorbed.

Step 4: Simulate a 503 and confirm recovery

node -e "console.log('test with a mocked 503 on first attempt, agent should succeed on the second')"

Expected: The agent recovers instead of aborting.

When to use this

• A translation agent aborts on the first Crowdin API error
• Transient 5xx or 429 kills the sync

When NOT to use this

• The error is 401, retrying will not fix auth
• The upload succeeds but strings are wrong, different problem

Tool and version compatibility

• Crowdin API v2, any agent upload wrapper
• Retryable: 429 and 5xx

Variant phrasings

retry storms from many agents

Add jitter to the backoff so parallel agents do not retry in lockstep.

partial upload before the error

Make uploads idempotent or check state before retrying, so a retry does not duplicate.

Why it happens

Agents often wrap API calls with try/catch that treats every error as fatal. Crowdin's transient errors are designed to be retried, so failing fast on them turns a blip into a broken sync.

Edge cases

• Log each retry with the attempt number, silent retries hide chronic flakiness
• Cap total retry time, a 10-minute retry loop is its own outage
• Alert after final failure, retries should not swallow the error forever

Provenance

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