docAnalyzer

When something goes wrong

What to do when a chat, upload, or workflow fails, and what to send support if it doesn't clear.

If an action fails (a chat doesn't answer, an upload doesn't go through, a workflow stops mid-run) the recovery is almost always the same three moves. Run them in order.

The recovery flow

  1. 1

    Retry once. A lot of failures are transient: a provider blip, a network hiccup, a brief rate cap. Try the same action again before doing anything else.

  2. 2

    Switch the model. If the retry fails the same way, pick a different model and try again. Provider-specific issues (one provider down, one model returning bad output) clear immediately when you switch. See Pick a model.

  3. 3

    Ask support with the trace ID. If retry + model-switch both fail, copy the trace ID from the chat and send it to support. The trace ID lets us look up exactly what happened on the backend.

Where to find the trace ID

When a chat action fails, the trace ID appears next to the failure message in the chat. Copy it.

If you don't see one, take a screenshot of the failure and the surrounding chat instead.

When the recovery flow isn't the answer

A few categories of failure have a more direct fix than retry / model-switch / support:

  • You're at a plan limit. Upload quota, storage cap, daily chat cap, credit balance: the failure message names the limit. You can't retry your way past it; you either wait for the reset or upgrade. See Plans and credits and How credits work.
  • Your message is over the prompt limit. That usually means document content was pasted into the message box. Add it as a document instead — the "Add as document" button on the message box does it in one click — then ask your question about it. The cap is the same on every plan, so this one isn't fixed by upgrading.
  • A document didn't process. Upload-side issues have their own recovery. See My document didn't process.

What to send support

When you do reach out, include:

  • The trace ID (if you have one).
  • What you were doing: "uploading a 40-page PDF", "asking Focus to summarize a dataset of 12 docs", "running the Blueprint workflow".
  • The URL of the page where the failure happened.
  • Roughly when it happened (within the hour is fine).

API errors

API consumers see HTTP status codes verbatim. These are stable and worth recognizing:

Code Meaning
401 Missing, malformed, or revoked API key. Check the Authorization: Bearer <key> header. See API keys.
413 Document upload exceeds the per-file size cap. Same limit as the app.
429 Rate-limited against per-key or per-account caps. Slow down and retry with backoff.
5xx Server-side issue. Retry with exponential backoff; if it persists across retries, contact support.

The response body of a 4xx or 5xx includes a trace ID; send it with any support request.

What's next

Was this helpful?