Troubleshoot an integration
Use error codes, correlation IDs and retained receipts to recover without duplicating work.
Start with the response’s structured error object. Retain its code, correlation_id, HTTP status and any returned receipt. For a run, also retain agent_id, run_id, the request’s operation key and the last accepted event cursor. Keep credentials, prompts and source content out of diagnostic reports.
Identify the failure boundary
| Symptom | Inspect | Next action |
|---|---|---|
| Cannot connect to the local example | Sandbox process, loopback address and port | Start python3 examples/sandbox/server.py; use http://127.0.0.1:8787/v1. No provider credentials are needed. |
| Missing Python module or unpublished SDK package | Installed archive and interpreter | Follow SDK preparation, or start with the curl-only request. |
| 401 | Selected API root and issued credential | Correct or rotate the credential through your control plane. A key prefix is not proof that a key was issued. |
| 403 | Advertised scope, feature entitlement and resource access | Use authentication and retrieval permissions. Changing a caller-supplied tenant ID cannot grant access. |
| 404 or unavailable operation | Deployment’s capability registry and API version | Compare the actual deployment with capability discovery, not a different source snapshot. |
| 422 | error.issues and the deployed request schema | Correct the field/type/enum; inspect the API reference. Do not retry unchanged invalid input. |
| 429 or 503 | Error code, retryability, Retry-After when present, original operation key | Apply retry safety. A retryable transport error does not authorise creating a new mutation. |
| No sources or missing evidence | Evidence availability and selected retrieval policy | Distinguish absent and unavailable evidence; inspect index freshness and permissions. |
| Draft text disappears or a stream closes early | Final event, revision and retained cursor | Apply the final revision and replay rules. Do not display a draft as a verified final answer. |
| Agent remains pending or awaiting approval | Original receipt, status and pending action | Poll the original run; inspect required approvals and deadlines. |
| Completed run, missing download or webhook effect | Artifact and delivery receipts | Follow completion and replay; transport acknowledgement is not receiver business completion. |
Recover an uncertain mutation
A connection failure can occur after Q accepted work. Preserve the original request, key and receipt. Poll an existing run or use the operation’s documented replay/recovery path. If dispatch is explicitly uncertain and no authoritative receipt can be recovered, reconcile with the operator using the correlation ID. Creating a new key can start duplicate work.
The qualified examples retain this uncertainty in their local journal and stop automatic starts. Do not delete that journal to force a retry. See durable agent recovery and idempotency.
Diagnose a slow run
Use run diagnostics to distinguish lifecycle waits, retrieval/provider work, incomplete usage, spending reservations and delivery state. Observations are limited to your authorised retained run metadata. Missing evidence is not zero duration or zero cost. Supply a correlation ID and run identity to your operator; never include a bearer token or source document.
Unavailable judgement or command classification
If a judge cannot verify completion, or required command classification cannot approve an action, inspect the configured model purpose, credentials and tenant routing policy with your operator. Missing model evidence does not authorise success or execution. Preserve the existing run and approval request while the configuration is corrected; restarting with a new key can duplicate work. See required approvals.
Browser failures
The browser should call your application backend, which authenticates the user and maps permitted resources. Do not solve a CORS or 401 problem by placing a Q service key in JavaScript. Compare your implementation with the backend proxy contract. The loopback starter’s development session is not production authentication.