Errors

Error shape

Errors are JSON with a single error string, and the HTTP status tells you the class of problem.

{ "error": "Target language 'es' is not enabled for this site." }

Branch on the status code first. Match on the message only for the specific cases below; the messages are quoted exactly as the API returns them.

The one exception: a batch job that couldn't be translated is not an HTTP error. Batch results returns 200 with "status": "failed" and an error string.

Status codes

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

500 Internal Server Error

{ "error": "An unexpected error occurred during authentication." }

Retry with exponential backoff. If it keeps happening, contact us with the time of the request and the job_id if there was one.

Retrying

• Do retry 500 responses and network timeouts. Wait 1 second, then 2, 4, 8, up to a limit you choose, and add a little random jitter.
• Back off if you hit a plan limit. Rate limits depend on your plan; the Batch plan allows 20 calls per hour. Treat 429 the same way as 500.
• Don't retry 401, 403 or 422 unchanged. They will fail the same way.
• Batch requests are safe to resubmit. The job_id is deterministic for the same input and target language.

async function translateWithRetry(body, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch("https://api.fluentc.ai/ai_agent/translate", {
      method: "POST",
      headers: {
        Authorization: process.env.FLUENTC_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });
    if (res.ok) return res.json();

    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || i === attempts - 1) {
      const { error } = await res.json().catch(() => ({}));
      throw new Error(`${res.status}: ${error ?? res.statusText}`);
    }
    const delay = 1000 * 2 ** i + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
}