Skip to content

Errors

All API errors return a JSON body with a consistent structure.

Error Format

{
  "detail": "A human-readable description of the error."
}

Some errors include additional fields for context:

{
  "detail": "Premium quality requires a paid plan",
  "required_plan": "starter"
}

HTTP Status Codes

Status Name Description
400 Bad Request Invalid parameters, malformed JSON, or missing required fields.
401 Unauthorized Missing or invalid API key.
403 Forbidden Insufficient plan for the requested feature (e.g. Premium quality, Google Drive, account glossaries); or insufficient role (member attempting owner-only operation).
404 Not Found Resource does not exist or does not belong to your account.
409 Conflict Resource already exists, state conflict, or job not yet in a terminal state.
410 Gone Resource has been permanently deleted.
413 Payload Too Large File or text exceeds the allowed size limit.
415 Unsupported Media Type File format is not supported.
422 Unprocessable Entity Validation error -- the request is well-formed but semantically invalid.
429 Too Many Requests Rate limit exceeded. Back off and retry.
500 Internal Server Error Unexpected failure on the server. Contact support if persistent.
503 Service Unavailable Temporary overload or maintenance. Retry after a short delay.

Common Error Scenarios

401 Unauthorized

{
  "detail": "Invalid or missing API key"
}

Check that you are passing the API key in the X-API-Key header.

403 Forbidden -- Tier Gate

When a feature requires a higher plan:

{
  "detail": "Premium quality requires a paid plan",
  "required_plan": "starter"
}

Upgrade your plan via the Dashboard or PATCH /v1/account/plan.

Other 403 scenarios include:

  • Attempting to create API keys on the Free plan
  • Using Google Drive integration without a Professional (or higher) plan
  • A member attempting an owner-only operation (e.g. renaming the account)

409 Conflict

{
  "detail": "Job not yet complete"
}

The job result or download endpoint was called before the job finished. Poll GET /v1/jobs/{job_id} until the status is terminal, or use webhooks.

413 Payload Too Large

{
  "detail": "File exceeds maximum size of 50 MB"
}

Reduce the file size or split the content into smaller chunks.

422 Unprocessable Entity

{
  "detail": "target_lang is required"
}

The request body passed JSON validation but is missing a required field or contains an invalid value. Check the endpoint documentation for required fields.

429 Too Many Requests

{
  "detail": "Rate limit exceeded"
}

You have exceeded the per-key rate limit (50 requests per minute). Implement exponential backoff:

import time
import requests

def request_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = 2 ** attempt
        time.sleep(wait)
    return response

async function requestWithBackoff(url, headers, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, { headers });
    if (response.status !== 429) return response;
    const wait = Math.pow(2, attempt) * 1000;
    await new Promise((r) => setTimeout(r, wait));
  }
}

Retry-After header

When present, the Retry-After header indicates the number of seconds to wait before retrying. Prefer this value over a fixed backoff schedule.

Rate Limiting

API requests are rate-limited per API key to protect service quality.

Limit Value
Requests per minute 50
Concurrent jobs 50

When the rate limit is exceeded, the API returns 429 Too Many Requests. Use the Retry-After header (if present) to determine when to retry.

Batch endpoints

Batch endpoints (/v1/jobs/batch-text, /v1/jobs/batch-file, /v1/jobs/batch-csv) count as a single request regardless of the number of target languages.