When it does not work
Troubleshooting
Almost every problem is visible in one of two places: the error body (code, message, field errors) or the run trace. Start there before anything else.
Common failures
| symptom | likely cause | fix |
|---|---|---|
| 401 on every call | Key revoked, or sandbox key against production | mynd auth status; check the key prefix |
| scope_denied mid-run | Run requested a source the key lacks | Grant the scope named in the error, or drop the source |
| step_limit on simple prompts | Vague prompt forcing exploratory planning | Narrow the ask; raise max_steps only if genuinely multi-step |
| Summary cites wrong document | Retrieval pulled a near-duplicate | Read the trace's context items; tighten filters or dedupe ingestion |
| Webhook never arrives | Endpoint paused after failures, or signature rejects | Dashboard → endpoint status; mynd webhooks tail to compare |
| Agent stops without acting | Approval gate reached, nobody approving | Poll run.pending_actions or subscribe to run.awaiting_approval |
| 429 at low traffic | Burst concentration inside one window | Smooth bursts; batch embeddings; check per-bucket headers |
Reading a trace for debugging
GET the run with include_trace=true. Check, in order: the plan (did it decompose the way you expected?), the context entries (what was fetched, what was not), each step's action, and the result. Most 'the model is wrong' reports are actually 'the model never saw the right context' — and the trace shows that directly.
When to contact support
Include the run id and the X-Request-Id of the failing call — with those two we can replay the exact execution. 500s with the same request id recurring, audit-log discrepancies, or suspected cross-project visibility go straight to support@myndlabs.ai with [urgent] in the subject.