FutureSmart Developer Docs
Open Database Agent

Errors and limits

The error format, every status code the API returns, question limits, model keys and timeouts.

Error format

Errors are JSON with a detail field. Most are a sentence:

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

Some carry a machine-readable code inside detail, which is what your code should branch on:

JSON
{
  "detail": {
    "code": "provider_key_missing",
    "message": "No OpenAI API key is configured for this workspace. Add your OpenAI API key under Credentials, then ask again."
  }
}

Request validation errors (422) list each problem:

JSON
{ "detail": [{ "type": "missing", "loc": ["body", "query"], "msg": "Field required" }] }

Status codes

StatusWhenWhat to do
400detail.code is provider_key_missing, provider_key_invalid, provider_key_rejected or a related provider-key code: the account's model key is missing or the provider refused it.Add or fix the OpenAI key on the app's Credentials screen.
401No key, an unknown or revoked key, a key sent as Authorization: Bearer, or a key used on a route that is not under its agent.Send a current key in X-API-Key; call routes under /v1/agents/{your agent}.
403The key belongs to a different agent, or the route is one keys may not use (API keys, invitations, the connection password, deleting the agent).Use the key issued for this agent; do owner tasks in the app.
404Unknown agent, or a session_id that belongs to another agent.Check the ids; start a new conversation by leaving out session_id.
422The body failed validation — for example query is missing.Fix the request using detail[].loc.
429The daily question limit is reached (see below).Wait until the time in the message, or add your own model key.
500The agent has no database connected, or an unexpected server error.Connect a database in the app; retry later and report persistent errors with the trace_id.
503A dependency was briefly unavailable (for example while checking a key).Retry with backoff.

When streaming, errors that happen after the stream has started arrive as a final full_metadata line with an error field and HTTP status 200. See Streaming.

Question limits

Hosted agents answer up to 20 questions in any rolling 24 hours per account, shared by every agent the account owns and every way of asking — the app, the website chat bubble, the full-page link, the API and MCP. When the limit is reached the API returns:

JSON
{ "detail": "Query limit reached: 20 of 20 in the last 24 hours. You can ask again after 14:05 UTC. …" }

with status 429. The limit is lifted automatically once your own model provider keys cover every model your agents use — add them on the app's Credentials screen. Need more on the platform key? Contact FutureSmart.

The shared sample agent in the app has its own allowance, shown in the app.

Model keys

Answers are generated by a language model, billed to a model provider key:

  • Your own key — the default for new accounts. Add your OpenAI key on the app's Credentials screen. Until you do, questions return 400 with detail.code = provider_key_missing.
  • The platform key — accounts created before 22 October 2026 run on FutureSmart's key unless they add their own.

Your Database Agent API key and your OpenAI key are different things: the first lets your code call this API, the second pays for the model behind it. Never send your OpenAI key to this API's X-API-Key header.

Timeouts and retries

  • A question typically takes 10–30 seconds and can take longer on large schemas or first questions after a database is added. Use a client timeout of at least 120 seconds; the MCP server uses 180.
  • Retry 429 only after the time in its message, and 500/503 with exponential backoff. Don't retry 4xx errors other than 429 unchanged — they will fail the same way.
  • A retried question is a new question: it counts toward your limit again and may be phrased differently.

Size limits

  • Answers return at most 50 rows inline. Larger results carry a 10-row preview and an export_url to the full CSV — see exporting rows.
  • PostgreSQL and MySQL databases are supported.