Troubleshooting

Common OptimAI Search setup and runtime issues.

Most issues fall into three buckets: credentials, request shape, or web retrieval constraints.

Authentication fails

Check that OPTIMAI_API_KEY is present in the runtime environment and that the request includes the X-API-Key header.

test -n "$OPTIMAI_API_KEY" && echo "key is set"

X-API-Key: sk-...

Empty sources

Make the query more specific. For scrape requests, confirm the URL is public and reachable without login, bot protection, or a private network.

Try changing:

{
  "query": "latest OpenAI agent framework changes"
}

to:

{
  "query": "OpenAI Agents SDK release notes and breaking changes this month"
}

Slow response

Lower the source limit for the first request. Then add a product-specific timeout and retry policy.

const controller = new AbortController()
const timeout = setTimeout(() => controller.abort(), 20_000)

try {
  await fetch("https://api-onchain.optimai.network/v1/search", {
    method: "POST",
    signal: controller.signal,
    headers: {
      "X-API-Key": process.env.OPTIMAI_API_KEY ?? "",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: "OptimAI Search", limit: 3 }),
  })
} finally {
  clearTimeout(timeout)
}

429 or 5xx responses

Retry only with bounded backoff. Do not retry 400 or 401; fix the request shape or credentials instead.

const retryable = response.status === 429 || response.status >= 500

Agent cannot read docs

Send the agent to /llms.txt first, then to a specific markdown page such as /docs/quick-start.md.