Skip to main content

​
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

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. If the check fails everywhere — or orders are running but behaving oddly — open the Ollang Status page before digging further. It reports live availability, open incidents, and scheduled maintenance across the platform and its APIs.

​
Authentication

  • 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 (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.
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.
Set OLLANG_API_KEY in your shell or .env so the agent can read it once and persist it across the session:

​
File Uploads

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 endpoint over web uploads.
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 page. Image-to-image translation needs JPEG, JPG, or PNG via Direct Upload specifically — see the Order Types table.
The platform takes the stored file’s extension from the filename in the multipart file part, not from the name field. A part sent without one — a bare Blob in JavaScript defaults the filename to blob — is stored as <name>.blob, which the document pipeline cannot read.Send the file under its real name. The three-argument append requires a Blob, so wrap raw bytes rather than passing a Buffer or Uint8Array straight in — those throw TypeError: parameter 2 is not of type 'Blob':
A File works too and carries the name itself, but it is only a global from Node 20 onwards — on Node 18 use the Blob form above.In the Node SDK, pass filename alongside a Blob — see Node.js Library. In the Python SDK, pass a path, or filename= alongside raw bytes.Uploads whose extension the platform cannot read are now rejected with a 400 before the project is created. Before that, the upload was accepted, the document pipeline failed on it, and Create Order against the resulting project returned 404 UploadRecordNotFoundException — with an orphan project left behind on every retry.
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.
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 entries on After Effects upload reliability and end-to-end AE localization.

​
Orders

Use the projectId returned from your most recent Direct File Upload response. Projects are scoped to the account that owns the API key — keys from another account cannot see them.
orderType must be one of cc, subtitle, document, aiDubbing, or studioDubbing. See Order Types.
targetLanguageConfigs must be a non-empty array. Each entry creates a separate order. Language codes follow Supported Languages.
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.If you suspect something is wrong, capture the orderId and recent GET /integration/orders/<orderId> response and contact support.
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.

​
Callbacks (callbackUrl)

  • 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 if you don’t receive a callback within a reasonable window.
Treat callback handlers as idempotent. Use the orderId + completedAt as a dedup key, or upsert into your store keyed by orderId.
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.

​
QC and Human Review

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.
Several options:
Review gates respect qcThreshold routing rules — orders may be re-routed automatically. Use Cancel Human Review to revert to the AI-only state and refund the review credits if priority changes.

​
Networking and 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.
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.
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.If you need to allowlist Ollang hosts with your network or security team, trust.ollang.com has the security and compliance documentation they’ll usually ask for.

​
SDK Issues

Ollang is a named export:
It is also the default export, but up to and including 0.4.0 the default import resolved to the module namespace under native ESM rather than to the class, so import Ollang from "@ollang-dev/sdk" threw. The named import works on every version.
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.
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.
Allow it via TMS_CORS_ORIGINS:
Multiple origins are comma-separated. See SDK Quickstart.

​
What to Send Support

Check the Status page first — if there’s an open incident, the answer may already be there. Otherwise, when opening a ticket at 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.
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.

​
Status, Security, and Compliance

  • status.ollang.com — live service status, incident history, and scheduled maintenance windows. Check it before filing a ticket about availability.
  • trust.ollang.com — the Ollang Trust Center: security, privacy, and compliance documentation. Start there for vendor security reviews and questionnaires.