Error Reference

All API errors return a JSON response with an error field describing the issue.

{
  "error": "Error message here"
}

HTTP Status Codes

Handling Errors

Rate Limiting (429)

When you receive a 429 error, implement exponential backoff:

async function translateWithRetry(text, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch("/api/v1/translate", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ text }),
    });

    if (res.status === 429) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    return res.json();
  }
  throw new Error("Max retries exceeded");
}

Quota Exceeded

When your monthly quota is exhausted:

1. Check your current usage via GET /usage
2. Upgrade your plan in Settings → Billing
3. Wait for the next billing period

Authentication Errors

If you receive a 401 error:

1. Verify your operator token is correct
2. Check if the token has been revoked or expired under Account → Operator tokens
3. Ensure the Authorization header format is Bearer opt_your-token
4. Legacy sk- keys no longer work; create an operator token instead

Scope and Permission Errors

If you receive a 403 error:

1. Pass workspace when the token can access multiple workspaces
2. Confirm you still hold the owner or admin role where the token translates (detection and usage only need membership)
3. Confirm the workspace or project is inside the token's scope