Errors and recovery
Handle MCP transport errors, permission failures, stale sources, bounded output, and safe retries.
On this page
Identify the failure layer
Authentication, endpoint checks, and rate limits can fail at the HTTP layer before MCP tool execution. A tool failure is returned with isError: true and a JSON error inside a text content block:
{
"isError":true,
"content":[{
"type":"text",
"text":"{\"error\":\"Task source version changed\",\"status\":409}"
}]
}Do not rely only on HTTP success: inspect the MCP result's isError. Tool error text is sanitized; unexpected server failures use INTERNAL_ERROR instead of exposing internal details.
Status and recovery
| Status | Common cause | Recovery |
|---|---|---|
400 | Invalid input, extra fields, malformed or mismatched cursor | Check the tool's schema. Restart pagination with the same filters if needed. |
401 | Missing, expired, revoked, or wrong-workspace bearer token | Let the client refresh or start a new browser login. Confirm the endpoint matches the authorized workspace. |
403 | Scope, role, membership, plan, claiming-grant, host, or origin restriction | Verify the current workspace access, consented scopes, and endpoint. A different grant cannot report someone else's claim. |
404 | Research, task, or authorization request unavailable to this user | Refresh the list; restart login if consent expired. Do not infer that another workspace's object exists. |
405 | Non-POST request to the MCP endpoint | Use an MCP client and perform a real tool call. Browser navigation is not a test. |
409 | Stale source version, occupied claim, reused ID with changed data, terminal run | Re-read state and follow the recovery rules below. |
413 | Projected result exceeds the output bound | Request a smaller page and use the tool's pagination. |
429 | Rate limit | Back off and reduce parallel requests; avoid repeated re-registration. |
500 | Unexpected server failure | Keep request/event IDs for safe retries and share the time and tool name with support. |
503 | MCP disabled or temporarily unavailable | Check the setup page's availability and try again later. |
Some oversized snapshot or single-record projections return 400 or 409 instead of 413; follow the specific error message. Lowering a page limit cannot make a single oversized record valid.
OAuth failures
invalid_request means parameters or a registered redirect are invalid. invalid_redirect_uri rejects an unsafe registration redirect. invalid_target means the resource is not a recognized workspace endpoint. access_denied means browser consent was declined. invalid_grant covers invalid or expired codes, refresh tokens, or grants.
Start a new login after an expired consent request or authorization code. Replace refresh tokens atomically after refresh; replaying an old refresh token revokes the grant. A new consent does not transfer an existing implementation claim to the new grant.
Claim and report conflicts
| Error | Meaning | Next action |
|---|---|---|
Task source version changed or Recommendation report version changed | The plan targets an outdated report or task source | Re-read the latest report, task, and evidence; create a new claim request after review. |
Task is not available; explicitly release an active claim | Another or previous run owns the task | Coordinate with the owner; explicitly release the latest eligible run if taking over. |
Request ID reused with changed payload or actor | A claim retry changed its content, user, or grant | Use the original exact request for a retry; a new attempt needs a new UUID. |
Event ID reused with changed payload | A report retry changed its content | Resend the original event or create a new event for a new update. |
Only the claiming grant may report this run | The user or grant differs from the claimant | Use the original authorized connection, or release and reclaim through a current eligible connection. |
Run is fenced or terminal | New events are disallowed after release or completion | Inspect the task; do not write progress into the old run. |
Run has been superseded | A later attempt exists | Work from the current claim; do not release the earlier run. |
Pagination and report readiness
Invalid or mismatched pagination cursor means the cursor was reused with a different workspace, role, query, source set, or report artifact. Restart from the first page. When reading a report, retain its returned version for follow-up pages.
NOT_READY is a successful get_report result, not an error. It means the requested saved artifact does not exist yet, including an unavailable explicit version. MCP does not generate reports. Check report readiness in Askdepth or read a different available artifact.
Rate limits
The current transport allows 60 authenticated MCP HTTP requests per minute per grant and 600 per minute per workspace. OAuth operations are separately limited, including dynamic client registration at 10 requests per hour per IP. These are request limits, not guarantees about tool throughput.
Reuse a configured OAuth client, serialize refreshes for a token, and use bounded pages. A temporary rate-limiting service failure returns 503; access is not bypassed.
Retry only what is safe
Read tools can be retried while their source remains available. Start and report writes have explicit idempotency IDs: keep the identical requestId or eventId and payload when retrying after a lost response. Never change data under an existing ID.
Release has no idempotency ID. If its response is lost, re-read the saved task and inspect Builds before releasing or claiming again. A cancelled old run rejects release; an AVAILABLE task can be claimed with a new request ID.
For support, share the tool name, timestamp, status, and sanitized message. Keep access tokens, refresh tokens, OAuth codes, and routine tokens out of logs and screenshots.