Your app supports five languages. Your translations look perfect. Your deployment is green.
Then your translation API goes down.
Suddenly, users see missing labels, half-translated screens, or an error message that makes everyone switch their phone back to English. Your beautifully multilingual application has become a multilingual pumpkin.
Translation API failures are not just API problems. They're production reliability problems. Without proper error handling, retries, caching, and fallback strategies, a temporary outage can break the user experience or interrupt your entire localization pipeline.
In this guide, we'll explore how to handle translation API failures in production, implement translation API error handling in JavaScript, recover failed AI translation jobs, and prevent a translation outage from becoming a full application outage.
A reliable translation system should:
The goal is simple: your app should remain usable even when its translation service isn't.
Translation APIs can fail for several reasons. Understanding the failure type helps you decide whether to retry, fall back, or stop the request entirely.
The provider might be experiencing downtime, maintenance, or internal errors. HTTP 500, 502, 503, and 504 responses can indicate temporary server-side problems.
What to do: Apply bounded retries with backoff. If failures continue, use cached translations or another fallback strategy.
Most providers limit how many requests you can make in a given period. If your application sends a translation request for every component, user action, or language simultaneously, you can hit those limits quickly.
What to do: Respect the API's Retry-After header, limit concurrency, and avoid retrying every failed request at the same instant.
A request can take too long because of network latency, overloaded servers, or a large translation payload.
What to do: Set explicit timeouts, retry only when appropriate, and provide a fallback when the deadline expires.
Expired credentials, incorrect API keys, missing permissions, and invalid configuration can prevent requests from succeeding.
What to do: Fix the underlying configuration. Repeatedly retrying an unauthorized request will not magically make your API key remember its password.
An API can return unexpected data, invalid JSON, missing fields, or a translation that has lost required placeholders.
For example, a source string such as:
Welcome back, {{name}}!
might come back as:
Welcome back!
The sentence is readable, but the required variable has disappeared.
What to do: Validate response structure, required keys, placeholders, and any format-specific constraints before accepting a translation.
Not every translation API failure should be handled the same way.
| Failure type | Example | Recommended response |
|---|---|---|
| Runtime failure | A user opens a page and a translation request fails | Use local or cached translations |
| Pipeline failure | A CI job fails while translating a new release | Record the failed job and retry safely |
| Partial failure | French succeeds but German and Japanese fail | Preserve successful results and retry only failed locales |
| Data validation failure | A translation removes a variable or returns invalid JSON | Reject the invalid result and flag it for repair |
This distinction matters because runtime localization resilience protects the person using your application, while localization pipeline recovery protects your development and release workflow.
Treating both as one generic retry loop usually creates more problems than it solves.
A good translation API timeout and retry strategy needs more than a try/catch block.
It should distinguish between temporary and permanent failures, cap the number of attempts, respect rate limits, and stop requests that exceed a reasonable deadline.
Here's a reusable example using fetch:
function sleep(ms) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
function getRetryAfterMs(response) {
const value = response.headers.get("Retry-After");
if (!value) return null;
// Retry-After can be seconds or an HTTP date.
const seconds = Number(value);
if (Number.isFinite(seconds) && value.trim() !== "") {
return Math.max(0, seconds * 1000);
}
const date = Date.parse(value);
return Number.isNaN(date)
? null
: Math.max(0, date - Date.now());
}
function isRetryableStatus(status) {
return status === 429 || status >= 500;
}
async function translateWithRetry(
url,
options = {},
{
maxAttempts = 3,
timeoutMs = 5000,
baseDelayMs = 300,
maxDelayMs = 5000,
} = {}
) {
let lastError;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const controller = new AbortController();
const timeout = setTimeout(
() => controller.abort(),
timeoutMs
);
let retryDelay = null;
try {
const response = await fetch(url, {
...options,
signal: controller.signal,
});
if (response.ok) {
return await response.json();
}
if (!isRetryableStatus(response.status)) {
throw new Error(
`Permanent translation error: HTTP ${response.status}`
);
}
retryDelay = getRetryAfterMs(response);
lastError = new Error(
`Retryable translation error: HTTP ${response.status}`
);
} catch (error) {
lastError = error;
if (
error.message.startsWith("Permanent translation error:")
) {
throw error;
}
} finally {
clearTimeout(timeout);
}
if (attempt === maxAttempts - 1) break;
const exponentialDelay = Math.min(
maxDelayMs,
baseDelayMs * 2 ** attempt
);
const jitteredDelay =
Math.random() * exponentialDelay;
await sleep(
retryDelay ?? jitteredDelay
);
}
throw lastError ?? new Error("Translation failed");
}This example illustrates the retry pattern, but production systems need additional safeguards:
The example retries rate limits, server errors, network failures, and timeouts. A production implementation should distinguish a timeout from a user-initiated cancellation, and it should avoid retrying malformed JSON as though it were a temporary network error.
When an API returns HTTP 429 Too Many Requests, it may include a Retry-After header that tells you when to try again.
Ignoring it can make a rate-limit problem worse.
Imagine 200 translation jobs fail at once. If all 200 immediately retry, they may trigger another rate limit, then another. Congratulations: you've built a tiny request storm.
A better approach is to:
If the provider doesn't specify a delay, use exponential backoff. If the requested delay exceeds your job's deadline, defer the job instead of keeping a worker occupied indefinitely.
For distributed applications, coordinate rate limits across workers where necessary. A per-process limit alone may not protect a shared API quota.
One of the simplest ways to prevent translation API failures from affecting users is to cache successful translations.
If your application has already translated a phrase, there may be no reason to call the API every time the phrase is displayed.
For example, consider a cache key based on the source text, target locale, and relevant translation version:
function translationCacheKey({
sourceText,
targetLocale,
version,
}) {
return [
version,
targetLocale,
sourceText,
].join(":");
}A cache lookup can follow this pattern:
async function getTranslation({
key,
translate,
cache,
}) {
const cached = await cache.get(key);
if (cached?.fresh) {
return cached.value;
}
try {
const value = await translate();
await cache.set(key, {
value,
fresh: true,
});
return value;
} catch (error) {
if (cached?.value != null) {
return cached.value;
}
throw error;
}
}This is a conceptual example. Your actual cache implementation needs to distinguish fresh from stale entries and retain stale values when refreshing them fails.
Depending on your architecture, you may cache:
That depends on the content.
A stale button label is often better than a missing button label. A stale legal disclaimer, price, safety instruction, or frequently changing policy may need stricter validation.
Use a policy that considers the content's importance, age, and risk. Don't assume every old translation is safe to display forever.
Cache fallback is not the same as translation correctness. A cached translation may be outdated, but it can still be a useful availability fallback when your product's rules permit it.
What happens when the primary translation provider stays down?
A robust system should define what to do next instead of hoping the provider recovers before your users notice.
A translation API fallback chain might look like this:
The exact order depends on your product. For a UI, local translations may be the best first choice. For newly submitted user content, you might need to queue the translation instead of showing a potentially misleading result.
A secondary provider can improve availability, but failover is not as simple as swapping URLs.
Providers may differ in:
Normalize provider responses behind a shared interface, validate the output, and test each provider independently.
Never assume that a successful HTTP response from a backup provider means the translation is correct.
Retries help with short-lived failures. They're less useful when a service is consistently unavailable.
This is where a circuit breaker helps prevent cascading failures in translation services.
A circuit breaker typically has three states:
For example, if repeated translation requests time out, the circuit can open temporarily. Your application can serve cached translations while the provider recovers.
A practical circuit breaker should include:
For a distributed application, consider whether circuit state should be local to each worker or coordinated across instances. Either approach can work, but it should match your traffic patterns and failure model.
Avoid retrying inside every layer. If the UI, backend, queue worker, and provider client all retry independently, one failed request can multiply into many more requests.
A particularly frustrating failure occurs when some locales succeed while others fail.
Suppose your release contains English, French, German, Spanish, and Japanese. The API completes English, French, and Spanish, but times out while processing German and Japanese.
A fragile pipeline may discard the entire result and start again.
A better design tracks status per locale and per translation unit.
| Locale | Status | Action |
|---|---|---|
| English | Complete | Keep the approved source |
| French | Complete | Preserve the successful result |
| German | Failed | Retry the failed work |
| Spanish | Complete | Preserve the successful result |
| Japanese | Timed out | Retry or requeue |
Don't overwrite a production translation file while it is only partially generated.
Instead:
This helps prevent partial translation file updates from breaking your application during deployment.
The unit of atomicity depends on your build system. Some projects can publish an entire locale bundle atomically; others need a versioned directory or release artifact.
A translation can return HTTP 200 OK and still be unusable.
Consider this source string:
Hello, {{name}}. You have {{count}} new messages.A translation that omits {{name}} or {{count}} may break interpolation or show incomplete content.
You can check for missing placeholders before accepting a translated string:
function extractPlaceholders(text) {
return new Set(
text.match(/\{\{\s*[\w.]+\s*\}\}/g) ?? []
);
}
function validatePlaceholders(source, translated) {
const sourcePlaceholders = extractPlaceholders(source);
const translatedPlaceholders = extractPlaceholders(translated);
const missing = [...sourcePlaceholders].filter(
(placeholder) => !translatedPlaceholders.has(placeholder)
);
const unexpected = [...translatedPlaceholders].filter(
(placeholder) => !sourcePlaceholders.has(placeholder)
);
return {
valid: missing.length === 0 && unexpected.length === 0,
missing,
unexpected,
};
}
const source = "Hello, {{name}}!";
const translated = "Bonjour !";
const result = validatePlaceholders(source, translated);
if (!result.valid) {
console.error("Translation failed validation:", result);
}This example handles double-curly placeholders. Adapt it for your framework's syntax, such as ICU message formats, plural rules, HTML tags, or named variables.
When validation fails:
This is particularly important when AI-generated translations are produced in batches. A syntactically valid response is not necessarily a valid translation.
AI translation workflows introduce additional failure cases: malformed structured output, truncated responses, invalid JSON, missing keys, or results that fail terminology and placeholder checks.
A reliable recovery process should make jobs resumable.
Each job should track:
When a job fails, retry only the work that remains incomplete and eligible for retry.
Step 1: Save job state. Record the input, target locale, and current status.
Step 2: Classify the error. Distinguish rate limits, network failures, server errors, invalid responses, and permanent configuration issues.
Step 3: Retry eligible failures. Use backoff, deadlines, and a maximum attempt count.
Step 4: Validate output. Check the schema, required keys, interpolation variables, and relevant formatting constraints.
Step 5: Resume from the last successful checkpoint. Avoid translating successful locales again unless their source content has changed.
Step 6: Escalate unresolved failures. Send exhausted jobs to a dead-letter queue or manual review process rather than silently dropping them.
A retry should not create duplicate translation jobs or overwrite a newer source revision with an older result.
Use stable identifiers, source-version checks, and idempotent job processing. If your provider supports idempotency keys for the relevant operation, use them appropriately.
This makes it easier to recover failed AI translation jobs in CI/CD without restarting the entire localization pipeline.
A successful request proves that your integration works when everything is healthy. It doesn't prove that it works when things go wrong.
Translation API resilience testing should deliberately simulate common failure scenarios before a release.
Test at least these cases:
For each test, define the expected outcome.
For example, if the primary API times out but a valid cached translation exists, the user should still see the cached text within the application's latency budget.
If a required placeholder is missing, the translation should fail validation instead of being silently published.
If a rate-limited job exhausts its retry budget, it should be scheduled for later or marked for investigation -- not disappear without a trace.
These tests help verify that your fallback chain, retry strategy, and recovery logic work together rather than independently.
You can't reliably improve failures you don't measure.
Useful metrics include:
Use structured logs with request or job IDs so you can follow a failure across your application and localization pipeline.
Set alerts for meaningful changes, such as a sudden increase in 429 responses, a sustained rise in translation latency, or a queue that keeps growing without completing work.
Be careful not to log API keys, sensitive source content, or personal data unnecessarily.
Handling API failures in your application is only part of localization reliability. Your development workflow also needs to keep translation files organized, synchronized, and reviewable.
A resilient localization workflow should:
No localization platform can make every third-party API infallible. The goal is to design a workflow where one failed request doesn't become a failed release -- or a broken application.
Before shipping your localization integration, confirm that:
Set request timeouts, retry transient errors with bounded exponential backoff, respect Retry-After, and use validated cached translations or a predefined fallback when requests fail. Monitor failure rates so persistent problems are detected quickly.
No. Retry temporary network errors, timeouts, rate limits, and selected server errors. Don't blindly retry invalid requests, expired credentials, or other permanent failures. Classify errors and enforce a retry budget.
Abort the request after a defined deadline, retry only when appropriate, and return a safe fallback if the application's latency budget is exhausted. Avoid unlimited retries, especially in user-facing requests.
Yes, when your content freshness and correctness rules permit it. Prefer fresh cached translations, and serve stale entries only under an explicit policy. Critical or frequently changing content may require stricter handling.
It depends on the content. A UI can often use bundled local translations or approved cached text. Newly submitted content may need to be queued for later translation. A secondary provider can help, but its output should be validated too.
Persist job status, classify errors, retry eligible failures, validate returned content, and resume from successful checkpoints. Keep job processing idempotent so a retry doesn't duplicate work or overwrite newer translations.
Generate files in a temporary location, validate their structure and placeholders, and publish only complete, validated artifacts. Keep the last known-good version available if a new translation build fails.
It is the practice of deliberately simulating API failures -- including timeouts, rate limits, server errors, malformed responses, and partial locale failures -- to verify that retries, fallbacks, and recovery mechanisms behave as expected.
The best tool depends on your workflow. Machine-translation APIs can translate content at runtime or in batches, while localization platforms help teams manage locale files, review changes, and keep translations aligned with source code. For repository-based localization and AI-assisted translation workflows, Babelize is one option to consider. Compare tools based on framework support, source-control integration, translation review, placeholder validation, pricing, and how well they fit your CI/CD process. No tool replaces application-level timeouts, retries, caching, and fallback handling for runtime API failures.
Babelize supports repository-based localization and AI-assisted translation workflows. Its sync detection documentation explains how teams can identify translation changes that need attention. Runtime protections such as retries, caching, and fallback behavior still need to be handled by your application.
Translation API failures are inevitable. A fragile localization system turns those failures into broken screens, delayed releases, and frantic debugging. A resilient one treats them as expected events.
Use bounded retries for temporary problems, caching for availability, fallback chains for continuity, circuit breakers for persistent outages, and resumable jobs for pipeline recovery. Then test those behaviors before your users discover the failure for you.
Because your users shouldn't need to learn English just because your translation API had an unscheduled vacation.
Build for failure. Recover gracefully. Keep your app multilingual.
--- - [All articles](https://www.babelize.co/blogs)