translation agent failed retrying crowdin upload after api error

Not specified by the original author.

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

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

Thread query: translation agent failed retrying crowdin upload after 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.

Not specified by the original author.

Fix the translation agent loop retrying a failed Crowdin upload

TL;DR

The agent retries forever because it never distinguishes retryable from fatal errors, so cap the retries and classify the error. A 401 retried 200 times is a loop, not resilience. Retry only transient errors, at most a few times, then stop and report.

The error

Translation agent log: retrying Crowdin upload, attempt 147
the API returns 401 every time, the agent never stops

Fix it

Step 1: Stop the runaway agent

pkill -f translate-agent || true

Expected: The loop stops.

Step 2: Check what the API actually returns

curl -s -o /dev/null -w "%{http_code}" -H "your auth header https://api.crowdin.com/api/v2/user

Expected: You see the real status, likely 401.

Step 3: Add a retry cap and error classification

node -e "console.log('max 3 retries, only on 429/5xx/network errors, everything else fails immediately')"

Expected: Fatal errors stop the loop on the first try.

Step 4: Fix the underlying 401, then rerun

node -e "console.log('refresh the credential, then run the agent -- it should fail fast or succeed, never loop')"

Expected: The agent completes or errors cleanly.

When to use this

• A translation agent loops retrying a failed upload
• Retry counts climb into the hundreds

When NOT to use this

• Retries are bounded and eventually succeed, that is working as designed
• The loop is in extraction, different fix

Tool and version compatibility

• Any agent with upload retry logic
• Crowdin API v2 error codes

Variant phrasings

loop on 429 without honoring retry-after

Bounded retries plus honoring retry-after. The cap alone still hammers the API.

loop across restarts, not within one run

The checkpoint says incomplete so it restarts forever. Fix the root error, then clear the poisoned state.

Why it happens

Unbounded retry with no error classification treats a permanent 401 like a transient blip. Each attempt fails identically, the agent tries again, and the loop runs until someone kills it, burning API quota the whole time.

Edge cases

• Alert on final failure, a capped retry that always fails is still a bug
• Exponential backoff without a cap is still unbounded, cap the count too
• Log the error body on final failure, the classification depends on it

Provenance

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

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

Thread query: translation agent loop detected retrying failed crowdin upload

TL;DR: The agent retries forever because it never distinguishes retryable from fatal errors, so cap the retries and classify the error. A 401 retried 200 times is a loop, not resilience. Retry only transient errors, at most a few times, then stop and report.

Not specified by the original author.

TL;DR

Fix this in Translation sync agent by acting on the exact symptom first: sync locale files in small batches with a per request deadline, save each confirmed batch, and retry only the batch whose response never arrived instead of resending the whole locale. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.

Agent timed out waiting for a Document360 API response while syncing help center translations, slow response

Use this when

• Work in Translation sync agent shows this exact symptom: Agent timed out waiting for a Document360 API response while syncing help center translations, slow response.
• The same symptom repeats after a retry with unchanged inputs.
• Readers or support agents are blocked until this item is corrected.

Not for this skill when

• The help center platform itself is down or returning outage notices. Resolve that first, then return here if this symptom remains.
• The content is correct and you only want a style or tone rewrite. That is an editorial pass, not this fix.

Steps

1. Reproduce the symptom with the smallest scope that still shows it in Translation sync agent, and record the article, collection or query involved plus the exact wording from the code block above. Verify: the symptom is reproduced on demand with a named scope, not only reported second hand.
2. Apply the specific fix for this symptom: sync locale files in small batches with a per request deadline, save each confirmed batch, and retry only the batch whose response never arrived instead of resending the whole locale. Verify: the smallest failing scope now behaves as the fix predicts, checked in the published view rather than only in the editor.
3. Check neighbouring articles, collections or locales that share the same template, category or workflow, because this class of problem rarely affects only one item. Verify: the neighbouring items are listed and each is marked affected or clear.
4. Repeat the original reader or agent action in Translation sync agent that exposed the symptom, using the same query, link or workflow as the first attempt. Verify: the action completes and the original symptom does not appear.
5. Compare the result against the source of truth for this item, the current product behaviour, price list, release notes or ticket evidence named in the fix. Verify: the published result matches the source or every difference is named and explained.
6. Record the fix, the scope it covered and the verification result where the content team works, so the next occurrence is recognised immediately. Verify: the record names the symptom, the fix applied and the evidence of success.

Variant phrasings

Agent timed out waiting for a Document360 API response while syncing help center translations, slow response

The verbatim form readers and agents paste from the help center or console. Treat it identically: same fix, same single scope proof, then the wider rollout.

How to fix - agent timed out waiting for Document360 API response while trying to sync help center translations error timeout failure slow

The how to phrasing for the same problem in Translation sync agent. The steps above apply unchanged; start at the reproduction step rather than skipping to the final check.

Translation sync agent troubleshooting for this symptom

The symptom first phrasing used when the full message is hidden. Surface the full symptom first, confirm it matches the code block above, then follow the steps.

Why it happens

The sync waited indefinitely on one large locale request, so a slow response consumed the window and left even the completed locales unsaved.

Edge cases

• The symptom appears in one locale, collection or audience view only. Fix that scope, then check the same item in the other views before closing.
• A cached or indexed copy keeps showing the old state after the fix. Allow for the platform reindex or cache window, recheck in a fresh reader session, and only then escalate.
• Two items have near identical titles. Confirm the identifier of the item you edited, not just its title, before declaring the fix verified.

Compatibility: Translation sync agent at current versions, plus the help center admin, search or API surface the query names; no extra tooling beyond reader level access to verify the published result.

Provenance

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

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

Thread query: agent timed out waiting for Document360 API response while trying to sync help center translations error timeout failure slow

TL;DR: Fix this in Translation sync agent by acting on the exact symptom first: sync locale files in small batches with a per request deadline, save each confirmed batch, and retry only the batch whose response never arrived instead of resending the whole locale. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.