FutureSmart Developer Docs
Open Document Intelligence

Errors and limits

The error format, every status code the API returns, usage limits, file limits and timeouts.

Error format

Errors are JSON with a detail field — usually a sentence:

JSON
{ "detail": "This API key is not valid for this collection" }

Validation errors (422) list each problem, including fields the endpoint does not accept:

JSON
{ "detail": [{ "type": "extra_forbidden", "loc": ["body", "top_k"], "msg": "Extra inputs are not permitted" }] }

Usage-limit errors (429) carry a structured body:

JSON
{
  "detail": {
    "error": "quota_exceeded",
    "message": "…",
    "would_exceed": "…",
    "remaining_quota": "…"
  }
}

Status codes

StatusWhenWhat to do
400The request is valid JSON but cannot be done: an unsupported file type, a file over a size, page or character limit, no document content sent, or an unknown search mode.Read detail; fix the input.
401No key, or an unknown or revoked key. On chat the message reads Chat is not publicly available for this knowledge base.Send a current key in x-api-key.
403The key belongs to another collection, the action is not allowed for keys (Collection API keys cannot call this endpoint), or the key's creator lacks the role for it.Use the right collection's key; do owner tasks in the app.
404Unknown document, or a session_id from another collection.Check the ids.
422Body validation failed — a missing query, a wrong type, an unknown field.Fix the request using detail[].loc.
429A usage limit is reached (see below).Wait for the period to reset, or raise the limit.
500An unexpected server error.Retry with backoff; report persistent errors with the request and time.

When streaming, a failure after the stream has started arrives as a data: {"error": "…"} frame with HTTP status 200. See Streaming.

Usage limits

Limits belong to the collection owner's account and count everything — the app, shared chats and every API key. Trial accounts start with:

LimitTrial
Messages (chat questions) per day50
Messages per month500
New conversations per month100
Documents50
Web pages (URLs)10
Collections10
Model tokens per month1,000,000

The app's Usage & Limits card shows your current use against your account's limits. When the owner adds their own model provider keys (Add credentials in the app), document ingestion is no longer capped by the trial item limits. Need more? Contact FutureSmart.

File limits

Direct upload (file)5 MB
PDF and DOCX10 pages
TXT, Markdown, HTML100,000 characters
Batch50 files per call
Upload URLvalid for 5 minutes; upload with the same Content-Type you requested

Timeouts and retries

  • Adding a document returns in about a second; reading it takes 10 seconds to a few minutes depending on length and type. Poll the status every few seconds rather than holding a request open.
  • A non-streamed chat answer takes 5–20 seconds. Use a client timeout of at least 60 seconds, 120 to be safe.
  • Retry 429 after its period resets and 500 with exponential backoff. Don't retry other 4xx errors unchanged.
  • Adding the same file twice creates two documents. To update a document in place, send your own source_id and last_modified in extra_metadata (see Add documents).