Limits and errors

Find tool and result limits, tool call failure reasons, Control Plane error types, conflicts, and retry guidance.

Use this page to check limits, interpret errors, and recover from failed or interrupted operations. A failed response does not by itself establish whether an operation ran.

The MCP API Reference defines Model Context Protocol (MCP) tools, arguments, and metadata. The Control Plane API Reference defines administration requests and field formats.

Limits and configurable defaults

Fixed limits are enforced by the API. Deployment defaults can be changed by your administrator. Request options and tool policies apply within their documented ranges. Confirm your deployment's settings before relying on a default.

Resource fields and naming

Tool discovery

Discovery can also stop at the response-size cap. When truncated is true, narrow the query. Raising limit only helps when the number returned reached that limit. See Handle truncated discovery results.

Caching and stored results

Exceeding the capture threshold does not guarantee a handle. Capture also depends on deployment and Gateway compression settings, tool policy, result eligibility, and storage availability. Automatic capture can fall back to the complete inline result. Explicit capture through run_tool_as_handle returns a tool error if it cannot create a handle, even if the source tool already ran.

See compression configuration and Work with stored results.

Context Surfaces

A successful search or capture can still be incomplete. Inspect completeness, over, and warning before treating counts of captured rows as totals for the source. Paging a handle does not retrieve records that were never captured. See stored-result interpretation.

Background indexing can also make search results incomplete. See Allow indexing to finish.

Agent key revocation

Revocation takes effect within the Identity Service cache lifetime, which is 300 seconds by default. Confirm that deployment setting with your administrator when planning key rotation or revocation.

MCP failures and safe retries

First identify the response type. HTTP connection or authentication failures can prevent an MCP response entirely. See MCP troubleshooting for those failures. Within MCP, a failed call can be a JSON-RPC error or a tool result with its error flag set.

Use machine-readable reason values to handle failures. Messages and result text explain the problem for people and can change between releases.

Decide whether a retry is safe

Tool failure metadata is in _meta["com.redis.context-gateway/failure"]. Its completion field describes whether the Gateway dispatched the call:

Explicit-capture failures include handleOutcome, which identifies the storage or policy outcome. Their completion is dispatched when the tool ran, or not_dispatched when the Gateway answered from its cache. No handle does not mean no result existed or no work was done.

A cache hit is reported by cache.status: hit and cache.ageMs in _meta["com.redis.context-gateway/invocation"]. Missing cache-hit metadata does not prove execution either: validation or authorization may have stopped the call first.

If completion is missing or uncertain, do not assume a mutating call is safe to repeat. Follow Retry uncertain operations.

JSON-RPC errors

These happen before any call to an Upstream. error.data holds reason and a traceId to give operators.

Tool results with an error flag

The failure metadata contains reason and completion. For an Upstream failure, it also contains stage and, for an Upstream JSON-RPC error, upstreamCode. Give operators the traceId from _meta["com.redis.context-gateway/invocation"] when investigating a tool failure.

Read raw Python MCP errors

With a direct Python MCP session, inspect the error flag before using result data. For example, after result = await session.call_tool(name, arguments):

if result.is_error:
    metadata = result.meta or {}
    failure = metadata.get("com.redis.context-gateway/failure", {})
    print(failure.get("reason"), failure.get("completion"))
else:
    print(result.structured_content)

Catch JSON-RPC failures separately. They are protocol exceptions rather than tool results. See Open a Python MCP session. Transport failures are also separate from tool results.

Python client error handling

With redis_iris.ContextGateway, call() returns a ToolResult for a successful response or a tool error that is not marked not_dispatched. A Gateway tool error marked not_dispatched raises ToolError, including an explicit-capture failure for a cached result. Rejected credentials or a missing Gateway raise ConfigurationError. Protocol failures, network failures, and timeouts can raise other exceptions.

After creating gateway and discovering a tool, handle these cases separately:

from redis_iris.errors import ConfigurationError, ToolError

try:
    result = gateway.call(tool_name, arguments)
except ConfigurationError as error:
    print("Check the Gateway endpoint and credentials:", error)
except ToolError as error:
    print("The Gateway did not dispatch the call:", error.reason)
else:
    if result.is_error:
        failure = result.meta.get("com.redis.context-gateway/failure", {})
        print(failure.get("reason"), failure.get("completion"), result.as_text())
    else:
        print(result.data)

A raw session obtained through gateway.client.connect() returns MCP result objects instead. Use is_error, structured_content, and meta as in the raw-session example. Keep transport and protocol exceptions separate from successful responses with an error flag.

Do not infer retry safety from the exception class alone when completion is uncertain. Follow Retry uncertain operations.

Control Plane API errors

Control Plane errors are problem details. Act on the HTTP status, the problem type, and the errors[] entries. Each entry identifies a body member with a JSON Pointer in pointer, or a path/query argument with parameter, and explains the issue in detail. Do not parse human-readable details into error codes.

Resolve conflicts

Updates and deletes take the resource's current revision as expectedRevision. Treat revisions as opaque values. A stale revision returns 412 with /errors/revision-conflict. Fetch the current state and reconcile your intended change before resubmitting it with the current revision. Substituting a new revision into an unchanged request can overwrite another update. Other state conflicts return 409:

Retry uncertain operations

Use bounded retries with backoff for reads and for tool calls that report not_dispatched, after correcting the cause. Read-only tool calls can be repeated without duplicating a mutation. For a mutating tool with dispatched, unknown, or missing completion, inspect the Upstream's state before deciding whether another call is safe.

A dispatched explicit-capture failure means the tool already ran even though no handle was created. Do not retry a mutating tool solely to obtain a handle.

Recover an uncertain Control Plane write

A timeout or lost response does not prove that a write failed:

1. Read the Gateway or Upstream's current state.
2. Check whether the intended change already took effect.
3. If another write is needed, reconcile it with the current state and use the current revision.

Do not blindly replay the original write or replace only its revision.

Resume an interrupted Upstream delete

A delete that stops partway can leave the Upstream marked for deletion while cleanup remains unfinished. Reads then return 404, which does not establish that cleanup completed.

Repeat the delete with the same Upstream ID to finish it. See Delete an Upstream and Context Surface index cleanup.