Operations

Troubleshooting & Errors

All API and MCP errors follow a consistent envelope. Check the error.code field first — each code maps to a specific cause and fix.

Error format

Every error response uses the same shape regardless of endpoint.

Error response

{

"error": {

"type": "invalid_request_error",

"code": "missing_session_id",

"message": "session_id is required for /v1/ask"

}

Error code reference

400missing_question

Cause

The question field was omitted or empty in the request body.

Fix

Include a non-empty question string in /v1/answer or /v1/ask.

400missing_session_id

Cause

session_id was not provided to /v1/ask.

Fix

Pass the session_id returned by /v1/upload or a prior /v1/answer call.

400invalid_session_id

Cause

The provided session ID is malformed, too long, or fails format validation.

Fix

Use the session ID exactly as returned by the API. Do not modify or truncate it.

400missing_accessible_source

Cause

No usable content was provided — no input, input_url, uploaded files, or existing session_id.

Fix

Include at least one source: inline input text, a signed HTTPS input_url, multipart files, or an existing session_id.

400unsupported_transport

Cause

input_url was a local runtime path (/mnt/data, sandbox:/, file://), a private network address, or was blocked by transport guardrails.

Fix

Pass extracted text as input, use a signed/public HTTPS URL, or use ti_create_upload_handoff in MCP environments.

400ask_upload_fields_not_supported

Cause

File or audio upload fields were included in a /v1/ask request.

Fix

/v1/ask is query-only. Upload files via /v1/upload first, then query the returned session_id.

401auth_expired

Cause

API key is missing, revoked, or the connector OAuth token has expired.

Fix

Check the x-api-key header is present and valid. Rotate the key from the developer dashboard if needed.

429rate_limited

Cause

Too many requests in a short window, or insufficient credits remaining.

Fix

Back off and retry. Check your credit balance from the dashboard. Top up if needed.

502upload_failed

Cause

The async ingestion run failed. Returned by /v1/answer when the background run completes with an error.

Fix

Check run_id in the response. Re-upload the document. Credits are refunded on system failures.

warnweak_extraction

Cause

Ingest succeeded but indexing quality is low — often scanned PDFs, image-only files, or very short inputs.

Fix

Re-ingest with richer extracted text. Use OCR or text-layer PDFs where possible. Do not base decisions on weak_extraction results.

Zero results after upload

Getting zero citations immediately after upload does not mean the document lacks the content. It usually means indexing is not yet complete.

Signal	Meaning	Action
retrieval_ready: false	Indexing still in progress	Poll `/v1/runs/{id}` until `status: completed`
citation_count: 0 + weak_extraction	Retrieval/indexing gap	Re-ingest with richer content or reindex
citation_count: 0 + grounded: false	No evidence found for this question	Rephrase or expand the query
citation_count: > 0, answer incomplete	Evidence retrieved, synthesis partial	Enforce claim-citation mapping; try higher `top_k`

Fast triage checklist

API key present?

Confirm x-api-key is set in every request header. Check the developer dashboard to ensure the key hasn't been revoked.

Correct endpoint?

Verify the request URL points to the right base. Use /v1/upload → /v1/ask for decoupled flow, or /v1/answer for one-call.

No local paths in input?

Never pass /mnt/data, sandbox:/, file://, or C:\Users\... paths as the input field. Extract content first.

retrieval_ready before asking?

For large files, always poll /v1/runs/{id} until status: completed before calling /v1/ask.

Network egress unblocked?

If using Claude Desktop or a local MCP client, ensure your firewall allows outbound HTTPS to the TI API domain.

Sufficient credits?

A rate_limited or 402 response usually means insufficient credit balance. Top up from the billing dashboard.