> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.ollang.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors, debugging tips, and what to send to support when something goes wrong.

# Troubleshooting

Most integration issues fall into a handful of buckets — authentication, uploads, callbacks, order state, or rate limits. Start here before opening a support ticket.

## First, Check the API Is Up

```bash theme={null}
curl https://api-integration.ollang.com/health
```

A `200` with `{"status":"OK"}` confirms connectivity. If this fails from your environment but works from your laptop, the issue is between your network and Ollang, not Ollang itself. Full reference: [Health Check](/apis/ollang-api-reference/health-check).

## Authentication

<AccordionGroup>
  <Accordion title="`401 Unauthorized` / `Invalid or missing API key`">
    * Confirm the header name is **`X-Api-Key`**, not `Authorization` or `X-API-KEY`.
    * Confirm the value is your active API key from the [Olabs Dashboard](https://lab.ollang.com) (project settings → API keys).
    * If you rotated your key recently, revisit any deployment or CI environment variable.
    * The `/health` endpoint does not require a key — useful as a sanity test.
  </Accordion>

  <Accordion title="MCP: 'Please reauthenticate'">
    OAuth refresh tokens can expire. Disconnect and reconnect the Ollang MCP server from your client (Claude Desktop, Cursor, etc.). Make sure the configured URL is `https://mcp.ollang.com/mcp`.
  </Accordion>

  <Accordion title="Skills: agent keeps asking for a key">
    Set `OLLANG_API_KEY` in your shell or `.env` so the agent can read it once and persist it across the session:

    ```bash theme={null}
    export OLLANG_API_KEY="<your-api-key>"
    ```
  </Accordion>
</AccordionGroup>

## File Uploads

<AccordionGroup>
  <Accordion title="`413 File too large`">
    Limits:

    * **Video**: 30 GB
    * **Documents**: 100 MB
    * **In-page API playground**: 5 MB (use a real client for anything larger)

    For very large videos, prefer the [Direct File Upload](/apis/ollang-api-reference/direct-file-upload) endpoint over web uploads.
  </Accordion>

  <Accordion title="`400 Invalid file format`">
    Confirm the file extension matches the actual content (e.g. `.mp4` for video, `.docx` for Office documents). The full supported list lives on the [Direct File Upload](/apis/ollang-api-reference/direct-file-upload) page. Image-to-image translation needs JPEG, JPG, or PNG **via Direct Upload** specifically — see the [Order Types](/apis/ollang-api-reference/order-types) table.
  </Accordion>

  <Accordion title="Upload succeeds but the project doesn't appear in my folder">
    Pass the destination `folderId` on the upload request. Without it, projects land in the default **API Uploads** folder. You can list folders with [Retrieve All Folders](/apis/ollang-api-reference/retrieve-all-folders).
  </Accordion>

  <Accordion title="Adobe After Effects (.ZIP) uploads are slow or fail">
    AE uploads run through a retry-with-backoff path and have a 5-minute conversion timeout. If a single asset is failing repeatedly, check that the .ZIP contains a clear main composition and try again. See the [changelog](/changelog) entries on After Effects upload reliability and end-to-end AE localization.
  </Accordion>
</AccordionGroup>

## Orders

<AccordionGroup>
  <Accordion title="`404 Project not found` on `Create Order`">
    Use the `projectId` returned from your most recent [Direct File Upload](/apis/ollang-api-reference/direct-file-upload) response. Projects are scoped to the account that owns the API key — keys from another account cannot see them.
  </Accordion>

  <Accordion title="`400 Invalid order type`">
    `orderType` must be one of `cc`, `subtitle`, `document`, `aiDubbing`, or `studioDubbing`. See [Order Types](/apis/ollang-api-reference/order-types).
  </Accordion>

  <Accordion title="`400 At least one targetLanguageConfig is required`">
    `targetLanguageConfigs` must be a non-empty array. Each entry creates a separate order. Language codes follow [Supported Languages](/apis/ollang-api-reference/supported-languages).
  </Accordion>

  <Accordion title="Order is stuck in `pending` or `ongoing` for a long time">
    Most AI orders complete within minutes; level-1 orders (with Human Review) depend on reviewer availability and may take hours. Some statuses (e.g. `waitingForCC`, `waitingForSubtitle`) indicate the order is gated on an upstream artifact. See [Order Statuses](/apis/ollang-api-reference/order-statuses).

    If you suspect something is wrong, capture the `orderId` and recent `GET /integration/orders/<orderId>` response and contact support.
  </Accordion>

  <Accordion title="Rerun didn't produce different output">
    Rerun re-executes against the **current** workflow. If the workflow, providers, custom instructions, and source content are unchanged, the AI may produce nearly identical output. Try updating the relevant Folder workflow or attaching guidelines before rerunning. See [Rerun Order](/apis/ollang-api-reference/rerun-order).
  </Accordion>
</AccordionGroup>

## Callbacks (`callbackUrl`)

<AccordionGroup>
  <Accordion title="Callback never fires">
    * Confirm `callbackUrl` is a fully-qualified `http(s)` URL.
    * Make sure your endpoint is reachable from the public internet — internal hostnames (`localhost`, `*.internal`) and IPv6 destinations are blocked at the SSRF guard.
    * Callbacks have a **10-second timeout**. If your handler takes longer to respond, Ollang treats it as a failure. Acknowledge quickly and process asynchronously.
    * Callback failures do not affect the order itself. Fall back to polling [Get Order by ID](/apis/ollang-api-reference/get-order-by-id) if you don't receive a callback within a reasonable window.
  </Accordion>

  <Accordion title="Callback fires twice">
    Treat callback handlers as idempotent. Use the `orderId` + `completedAt` as a dedup key, or upsert into your store keyed by `orderId`.
  </Accordion>

  <Accordion title="I need to validate the callback came from Ollang">
    Don't rely on the body alone. Pair the callback with a `GET /integration/orders/<orderId>` confirmation using your API key before acting on the contents.
  </Accordion>
</AccordionGroup>

## QC and Human Review

<AccordionGroup>
  <Accordion title="`autoQc` was set but no QC ran">
    `autoQc` only applies to **top-level** orders (orders created directly), not child orders generated as part of a parent workflow. It also requires `enableQCThreshold` on the client account.
  </Accordion>

  <Accordion title="QC scores look low — what now?">
    Several options:

    * Add **Custom Instructions** or **Guidelines** to steer the AI toward your tone and terminology. See [Memory, Guidelines, and Custom Instructions](/memory-guidelines-custom-instructions).
    * Attach a **Memory** (approved terminology) so future orders reference it.
    * Upgrade to **Level 1** via [Request Human Review](/apis/ollang-api-reference/request-human-review).
    * Change the AI provider in the [Folder workflow](/workflows-provider-architecture) and rerun.
  </Accordion>

  <Accordion title="Human Review is taking longer than expected">
    Review gates respect `qcThreshold` routing rules — orders may be re-routed automatically. Use [Cancel Human Review](/apis/ollang-api-reference/cancel-human-review) to revert to the AI-only state and refund the review credits if priority changes.
  </Accordion>
</AccordionGroup>

## Networking and Limits

<AccordionGroup>
  <Accordion title="Rate limits">
    Ollang enforces per-account rate limits. If you receive a `429`, back off exponentially and retry. For high-volume use cases, contact Ollang to discuss limits before launch.
  </Accordion>

  <Accordion title="Timeouts on long requests">
    Some operations (large uploads, AE conversions) intentionally take minutes. Increase your HTTP client's read/write timeouts (5–10 minutes is reasonable for uploads) and don't reuse a connection across unrelated requests.
  </Accordion>

  <Accordion title="VPN / proxy issues">
    Outbound traffic from your environment must reach `api-integration.ollang.com` and `mcp.ollang.com`. Some corporate proxies strip `multipart/form-data` headers or terminate long uploads — try a clean network as a comparison.
  </Accordion>
</AccordionGroup>

## SDK Issues

<AccordionGroup>
  <Accordion title="Asset Management server fails to start">
    Run `npx @ollang-dev/sdk start` from your project root where `ollang.config.ts` lives. Set `OLLANG_API_KEY` first. If you're developing the SDK from source, run `npm run build` in the SDK package.
  </Accordion>

  <Accordion title="No items appear after a project scan">
    Check `includePaths` and `includePatterns` in `ollang.config.ts`. The scanner has to match real files — e.g. `messages/*.json`, `locales/**/*.json`. Confirm your i18n files exist at those paths.
  </Accordion>

  <Accordion title="CORS error from a non-default dev origin">
    Allow it via `TMS_CORS_ORIGINS`:

    ```bash theme={null}
    TMS_CORS_ORIGINS=http://127.0.0.1:4200 npx @ollang-dev/sdk start
    ```

    Multiple origins are comma-separated. See [SDK Quickstart](/sdk/quickstart#cors-and-allowed-origins).
  </Accordion>
</AccordionGroup>

## What to Send Support

When opening a ticket at [info@ollang.com](mailto:info@ollang.com), include:

* The **`orderId`** (or `projectId`) you're asking about.
* The exact API endpoint and request method.
* The full response — status code, headers (especially `x-request-id` if present), and JSON body.
* Approximate **timestamp** of the request (UTC) so we can correlate logs.
* For SDK / MCP / Skills: the package version, agent, and OS.

<Warning>
  Do not paste your **API key**, **OAuth tokens**, or **callback secrets**
  into a support email or public GitHub issue. Redact them. We never need
  the key value to investigate an issue — the request ID and order ID are
  enough.
</Warning>