rmcp_openapi

Module error

Source
Expand description

Error handling for the OpenAPI MCP server.

This module provides structured error types that distinguish between validation errors (which return as MCP protocol errors) and execution errors (which appear in tool output schemas).

§Error Categories

§Validation Errors (MCP Protocol Errors)

These errors occur before tool execution and are returned as MCP protocol errors (Err(ErrorData)). They do NOT have JsonSchema derive to prevent them from appearing in tool output schemas.

  • ToolNotFound: Requested tool doesn’t exist
  • InvalidParameters: Parameter validation failed (unknown names, missing required, constraint violations)
  • RequestConstructionError: Failed to construct the HTTP request

§Execution Errors (Tool Output Errors)

These errors occur during tool execution and are returned as structured content in the tool response. They have JsonSchema derive so they can appear in tool output schemas.

  • HttpError: HTTP error response from the API (4xx, 5xx status codes)
  • NetworkError: Network/connection failures (timeout, DNS, connection refused)
  • ResponseParsingError: Failed to parse the response

§Error Type Examples

§InvalidParameter (Validation Error)

{
  "type": "invalid-parameter",
  "parameter": "pet_id",
  "suggestions": ["petId"],
  "valid_parameters": ["petId", "status"]
}

§ConstraintViolation (Validation Error)

{
  "type": "constraint-violation",
  "parameter": "age",
  "message": "Parameter 'age' must be between 0 and 150",
  "field_path": "age",
  "actual_value": 200,
  "expected_type": "integer",
  "constraints": [
    {"type": "minimum", "value": 0, "exclusive": false},
    {"type": "maximum", "value": 150, "exclusive": false}
  ]
}

§HttpError (Execution Error)

{
  "type": "http-error",
  "status": 404,
  "message": "Pet not found",
  "details": {"error": "NOT_FOUND", "pet_id": 123}
}

§NetworkError (Execution Error)

{
  "type": "network-error",
  "message": "Request timeout after 30 seconds",
  "category": "timeout"
}

§Structured Error Responses

For tools with output schemas, execution errors are wrapped in the standard response structure:

{
  "status": 404,
  "body": {
    "error": {
      "type": "http-error",
      "status": 404,
      "message": "Pet not found"
    }
  }
}

Validation errors are returned as MCP protocol errors:

{
  "code": -32602,
  "message": "Validation failed with 1 error",
  "data": {
    "type": "validation-errors",
    "violations": [
      {
        "type": "invalid-parameter",
        "parameter": "pet_id",
        "suggestions": ["petId"],
        "valid_parameters": ["petId", "status"]
      }
    ]
  }
}

This consistent structure allows clients to:

  • Programmatically handle different error types
  • Provide helpful feedback to users
  • Automatically fix certain errors (e.g., typos in parameter names)
  • Retry requests with corrected parameters

Structs§

ErrorResponse
Error response structure for tool execution failures

Enums§

CliError
CLI-specific errors for command-line argument parsing and validation
NetworkErrorCategory
Network error categories for better error handling
OpenApiError
ToolCallError
Error that can occur during tool execution
ToolCallExecutionError
Execution errors that occur during tool execution These return as Ok(CallToolResult { is_error: true })
ToolCallValidationError
Validation errors that occur before tool execution These return as Err(ErrorData) with MCP protocol error codes
ValidationConstraint
Individual validation constraint that was violated
ValidationError
Individual validation error types