Skip to content

Diagnose a Failed Request

Purpose

Use a failed model or MCP response to choose the next recovery step. This guide is for an application calling an existing deployment; service operators should use Operations troubleshooting.

Prerequisites

  • The response status, safe error code, and X-Mission-Control-Correlation-Id, when present.
  • The gateway URL, endpoint, and type of credential your application uses.
  • Access to the Team's Observability or an administrator who can inspect it. Never include a raw key or request content in a support message.

Procedure

  1. Check the endpoint and credential. Model requests go to the inference gateway, OTLP goes to the Collector, and browser authorization goes to the Console. An MCP client connection cannot authenticate a model request. Compare with the API route index.
  2. Inspect the whole response. Model endpoints use an OpenAI-style error object. MCP can return HTTP 200 with a JSON-RPC error or a tool result with isError: true; success at the HTTP layer does not mean the tool executed. Keep the safe error code and correlation ID.
  3. Choose the matching action below. For a 429, honor Retry-After when supplied. Do not automatically replay an action or a stream that may already have produced an effect.
  4. Find the request. Use its returned Trace ID in Observe → Traces. Open the request span and Request → Open decision to inspect the decision when your role permits it. If the Organization has not enabled telemetry.standardOtlp, the Trace has no spans; find the request under Observe → Requests instead. Missing inspection permission is separate from the original invocation failure.
  5. Verify recovery once. Retry only when the failure contract makes retry safe. Confirm the request's result or decision before submitting a potentially duplicated action.
What you received Next action
401 or authentication_failed Confirm the key belongs to this deployment, is active, and is sent as a Bearer credential. Replace a revoked/rotated key in the process; reload the client if it caches its environment.
operation_denied Ask a Team administrator to check resource enablement and the actual key policy. A new key alone does not fix authorization.
Empty model/tool list Check Team selection, enablement, and key policy; do not substitute a provider's raw model name.
unsupported_feature or capability_unavailable Check the model compatibility contract and the selected model's advertised capabilities.
MCP protocol/header rejection Check the supported revision, required headers, and _meta envelope against the MCP reference.
connector_user_auth_required Open the returned connection link, connect your own account, then follow the per-user Connector procedure.
approval_required Open the approval URL and wait for a separate authorized person. After approval, retry the identical tool and arguments as described in Approvals.
rule_blocked or a guardrail block Review the policy decision with an administrator; retrying the same input does not bypass the rule.
Product limit or provider rate limit Check usage and limits and the error's retry guidance.
Provider unavailable or tool invocation failed Give an administrator the safe correlation ID and failure time to check upstream health. Use the endpoint's recovery contract before retrying.

Expected result

You can identify whether the problem is connection setup, authentication, access, input compatibility, a policy/approval requirement, a limit, or an upstream failure, and take the corresponding recovery action.

Verification

The request completes with the expected model response or tool result, and its decision records the intended resource and outcome. Check isError for MCP results and stream error events as well as the HTTP status.

Failure recovery

If the response remains unclear, provide the endpoint, status/code, UTC time, and correlation ID to your administrator. If traces are missing, follow OpenTelemetry verification and Observe activity; an observation gap does not change the recorded authorization decision.