feat: use openrpc error types and add try_cause_as for typed error matching

Remove duplicated RpcError/RpcErrorCause from rpc_client.rs — now
imported from near_openrpc_client's errors module.

Simplify is_critical_* retry functions in utils.rs to use
RpcError::is_retryable() and try_cause_as<RpcTransactionError>()
instead of string-matching cause names.

Add SendRequestError::try_cause_as<T>() convenience method so
downstream users can pattern-match on typed RPC error enums
(RpcQueryError, RpcTransactionError, etc.) without unwrapping.

Re-export near_openrpc_client::errors as near_api::rpc_errors for
easy access to the typed error enums.

Author: r-near

Cargo.toml

@@ -55,7 +55,7 @@ near-gas = { version = "0.3", features = ["serde", "borsh"] }
 near-token = { version = "0.3", features = ["serde", "borsh"] }
 near-abi = "0.4.2"
 near-ledger = "0.9.1"
-near-openrpc-client = { git = "https://github.com/near/near-openrpc-client-rs.git", default-features = false }
+near-openrpc-client = { git = "https://github.com/near/near-openrpc-client-rs.git", branch = "feat/errors-module", default-features = false }
 
 # Dev-dependencies
 near-primitives = { version = "0.34" }

api/src/common/query/query_rpc.rs

@@ -1,12 +1,14 @@
 use async_trait::async_trait;
 
+use near_openrpc_client::{RpcError, RpcErrorCause};
+
 use crate::{
     NetworkConfig,
     advanced::{RpcType, query_request::QueryRequest},
     common::utils::{is_critical_query_error, to_retry_error},
     config::RetryResponse,
     errors::SendRequestError,
-    rpc_client::{RpcCallError, RpcClient, RpcError, RpcErrorCause},
+    rpc_client::{RpcCallError, RpcClient},
 };
 use near_api_types::Reference;
 
@@ -15,6 +17,25 @@ pub struct SimpleQueryRpc {
     pub request: QueryRequest,
 }
 
+/// Synthesize a `SendRequestError` for query-embedded execution errors.
+///
+/// NEAR's query RPC returns HTTP 200 with an `"error"` string field in the
+/// result body for WASM execution failures. We convert this into a proper
+/// `RpcError` with a `CONTRACT_EXECUTION_ERROR` cause so the retry logic
+/// and typed error matching work uniformly.
+fn query_execution_error(error_msg: &str) -> SendRequestError {
+    SendRequestError::from(RpcCallError::Rpc(RpcError {
+        code: -32000,
+        message: "Server error".to_string(),
+        data: Some(serde_json::Value::String(error_msg.to_string())),
+        name: Some("HANDLER_ERROR".to_string()),
+        cause: Some(RpcErrorCause {
+            name: "CONTRACT_EXECUTION_ERROR".to_string(),
+            info: Some(serde_json::json!({ "error_message": error_msg })),
+        }),
+    }))
+}
+
 #[async_trait]
 impl RpcType for SimpleQueryRpc {
     type RpcReference = Reference;
@@ -28,41 +49,15 @@ impl RpcType for SimpleQueryRpc {
         let request = self.request.clone().to_rpc_query_request(reference.clone());
         match client.call::<_, serde_json::Value>("query", request).await {
             Ok(value) => {
-                // NEAR's query method returns a successful JSON-RPC response even for
-                // WASM execution errors. The error is embedded as an "error" string field
-                // in the result body (e.g., {"error": "wasm execution failed...", "logs": []}).
-                // We need to detect this and convert it to a proper RPC error.
                 if let Some(error_msg) = value.get("error").and_then(|e| e.as_str()) {
-                    let cause_name = if error_msg.contains("CodeDoesNotExist") {
-                        "CONTRACT_EXECUTION_ERROR"
-                    } else if error_msg.contains("MethodNotFound")
-                        || error_msg.contains("MethodResolveError")
-                    {
-                        "CONTRACT_EXECUTION_ERROR"
-                    } else {
-                        "CONTRACT_EXECUTION_ERROR"
-                    };
-
-                    let err = SendRequestError::from(RpcCallError::Rpc(RpcError {
-                        code: -32000,
-                        message: "Server error".to_string(),
-                        data: Some(serde_json::Value::String(error_msg.to_string())),
-                        name: Some("HANDLER_ERROR".to_string()),
-                        cause: Some(RpcErrorCause {
-                            name: cause_name.to_string(),
-                            info: Some(serde_json::json!({
-                                "error_message": error_msg,
-                            })),
-                        }),
-                    }));
-                    return to_retry_error(err, is_critical_query_error);
+                    return to_retry_error(
+                        query_execution_error(error_msg),
+                        is_critical_query_error,
+                    );
                 }
                 RetryResponse::Ok(value)
             }
-            Err(err) => {
-                let err = SendRequestError::from(err);
-                to_retry_error(err, is_critical_query_error)
-            }
+            Err(err) => to_retry_error(SendRequestError::from(err), is_critical_query_error),
         }
     }
 }

api/src/common/utils.rs

@@ -1,13 +1,11 @@
-// New errors can be added to the codebase, so we want to handle them gracefully
-#![allow(unreachable_patterns)]
-
 use base64::{Engine, prelude::BASE64_STANDARD};
 use near_api_types::NearToken;
+use near_openrpc_client::{RpcError, RpcTransactionError};
 
 use crate::{
     config::RetryResponse,
     errors::SendRequestError,
-    rpc_client::{RpcCallError, RpcError},
+    rpc_client::RpcCallError,
 };
 
 pub fn to_base64(input: &[u8]) -> String {
@@ -34,57 +32,31 @@ pub fn to_retry_error<T>(
     }
 }
 
+/// Blocks errors: all known causes are retryable (UNKNOWN_BLOCK, NOT_SYNCED_YET, INTERNAL_ERROR).
 pub fn is_critical_blocks_error(err: &SendRequestError) -> bool {
-    is_critical_json_rpc_error(err, |rpc_err| {
-        match rpc_err.cause_name() {
-            Some("UNKNOWN_BLOCK") | Some("NOT_SYNCED_YET") | Some("INTERNAL_ERROR") => false,
-            _ => false,
-        }
-    })
+    is_critical_json_rpc_error(err, |rpc_err| !rpc_err.is_retryable())
 }
 
+/// Validator errors: all known causes are retryable (UNKNOWN_EPOCH, VALIDATOR_INFO_UNAVAILABLE, INTERNAL_ERROR).
 pub fn is_critical_validator_error(err: &SendRequestError) -> bool {
-    is_critical_json_rpc_error(err, |rpc_err| {
-        match rpc_err.cause_name() {
-            Some("UNKNOWN_EPOCH") | Some("VALIDATOR_INFO_UNAVAILABLE") | Some("INTERNAL_ERROR") => {
-                false
-            }
-            _ => false,
-        }
-    })
+    is_critical_json_rpc_error(err, |rpc_err| !rpc_err.is_retryable())
 }
 
+/// Query errors: retryable causes (NO_SYNCED_BLOCKS, UNAVAILABLE_SHARD, UNKNOWN_BLOCK, INTERNAL_ERROR)
+/// are not critical, but permanent errors (INVALID_ACCOUNT, UNKNOWN_ACCOUNT, etc.) are.
+/// NO_GLOBAL_CONTRACT_CODE is treated as retryable since it may not have propagated yet.
 pub fn is_critical_query_error(err: &SendRequestError) -> bool {
-    is_critical_json_rpc_error(err, |rpc_err| {
-        match rpc_err.cause_name() {
-            Some("NO_SYNCED_BLOCKS") | Some("UNAVAILABLE_SHARD") | Some("UNKNOWN_BLOCK")
-            | Some("INTERNAL_ERROR") => false,
-
-            Some("GARBAGE_COLLECTED_BLOCK")
-            | Some("INVALID_ACCOUNT")
-            | Some("UNKNOWN_ACCOUNT")
-            | Some("NO_CONTRACT_CODE")
-            | Some("TOO_LARGE_CONTRACT_STATE")
-            | Some("UNKNOWN_ACCESS_KEY")
-            | Some("CONTRACT_EXECUTION_ERROR")
-            | Some("UNKNOWN_GAS_KEY") => true,
-
-            // Might be critical, but also might not yet propagated across the network, so we will retry
-            Some("NO_GLOBAL_CONTRACT_CODE") => false,
-            _ => false,
-        }
-    })
+    is_critical_json_rpc_error(err, |rpc_err| !rpc_err.is_retryable())
 }
 
+/// Transaction errors: TIMEOUT_ERROR and REQUEST_ROUTED are retryable.
+/// INVALID_TRANSACTION, DOES_NOT_TRACK_SHARD, UNKNOWN_TRANSACTION are critical.
+/// INTERNAL_ERROR is treated as critical for transactions (different from queries).
 pub fn is_critical_transaction_error(err: &SendRequestError) -> bool {
     is_critical_json_rpc_error(err, |rpc_err| {
-        match rpc_err.cause_name() {
-            Some("TIMEOUT_ERROR") | Some("REQUEST_ROUTED") => false,
-            Some("INVALID_TRANSACTION")
-            | Some("DOES_NOT_TRACK_SHARD")
-            | Some("UNKNOWN_TRANSACTION")
-            | Some("INTERNAL_ERROR") => true,
-            _ => false,
+        match rpc_err.try_cause_as::<RpcTransactionError>() {
+            Some(Ok(RpcTransactionError::TimeoutError | RpcTransactionError::RequestRouted { .. })) => false,
+            _ => true,
         }
     })
 }
@@ -99,7 +71,6 @@ fn is_critical_json_rpc_error(
         SendRequestError::TransportError(err) => match err {
             RpcCallError::Http(e) => {
                 use reqwest::StatusCode;
-                // Check HTTP status for retryable errors
                 e.status().map_or(false, |s| {
                     !matches!(
                         s,

api/src/errors.rs

@@ -1,6 +1,8 @@
 use std::sync::Arc;
 
-use crate::rpc_client::{RpcCallError, RpcError};
+use crate::rpc_client::RpcCallError;
+use near_openrpc_client::RpcError;
+use serde::Deserialize;
 
 #[derive(thiserror::Error, Debug)]
 pub enum QueryCreationError {
@@ -288,6 +290,39 @@ pub enum SendRequestError {
     ServerError(RpcError),
 }
 
+impl SendRequestError {
+    /// Returns the underlying [`RpcError`] if this is a server error.
+    pub fn as_rpc_error(&self) -> Option<&RpcError> {
+        match self {
+            Self::ServerError(e) => Some(e),
+            _ => None,
+        }
+    }
+
+    /// Attempts to deserialize the RPC error cause into a typed per-method error enum.
+    ///
+    /// Convenience wrapper around [`RpcError::try_cause_as`]. Returns `None` if
+    /// this isn't a server error or if the server error has no cause.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use near_openrpc_client::errors::RpcQueryError;
+    ///
+    /// match send_err.try_cause_as::<RpcQueryError>() {
+    ///     Some(Ok(RpcQueryError::UnknownAccount { requested_account_id, .. })) => {
+    ///         println!("Account {requested_account_id} not found");
+    ///     }
+    ///     _ => {}
+    /// }
+    /// ```
+    pub fn try_cause_as<T: for<'de> Deserialize<'de>>(
+        &self,
+    ) -> Option<Result<T, serde_json::Error>> {
+        self.as_rpc_error()?.try_cause_as()
+    }
+}
+
 impl From<RpcCallError> for SendRequestError {
     fn from(err: RpcCallError) -> Self {
         match err {

api/src/lib.rs

@@ -66,6 +66,8 @@ pub mod rpc_client;
 
 pub use near_api_types as types;
 pub mod errors;
+/// Re-export per-method RPC error enums for typed error matching via [`errors::SendRequestError::try_cause_as`].
+pub use near_openrpc_client::errors as rpc_errors;
 pub mod signer;
 
 pub use crate::{

api/src/rpc_client.rs

@@ -1,5 +1,8 @@
+use near_openrpc_client::RpcError;
 use serde::{Deserialize, Serialize};
 
+pub use near_openrpc_client::errors;
+
 /// Thin JSON-RPC 2.0 client wrapping `reqwest::Client`.
 ///
 /// This replaces the OpenAPI-generated client with a minimal transport
@@ -30,61 +33,6 @@ struct RpcResponse {
     error: Option<RpcError>,
 }
 
-/// Error from a JSON-RPC call.
-///
-/// NEAR's RPC extends standard JSON-RPC errors with `name` and `cause` fields
-/// that carry structured, typed error information.
-#[derive(Debug, Clone, Deserialize)]
-pub struct RpcError {
-    pub code: i64,
-    pub message: String,
-    /// Deprecated by nearcore. Prefer `cause` for structured error data.
-    #[serde(default)]
-    pub data: Option<serde_json::Value>,
-    /// Error category: `HANDLER_ERROR`, `REQUEST_VALIDATION_ERROR`, or `INTERNAL_ERROR`.
-    #[serde(default)]
-    pub name: Option<String>,
-    /// Structured error detail with per-method error variant name and info.
-    #[serde(default)]
-    pub cause: Option<RpcErrorCause>,
-}
-
-/// Structured cause of an RPC error.
-#[derive(Debug, Clone, Deserialize)]
-pub struct RpcErrorCause {
-    /// The error variant name (e.g., `UNKNOWN_BLOCK`, `INVALID_ACCOUNT`).
-    pub name: String,
-    /// Additional structured information about the error.
-    #[serde(default)]
-    pub info: Option<serde_json::Value>,
-}
-
-impl RpcError {
-    pub fn is_handler_error(&self) -> bool {
-        self.name.as_deref() == Some("HANDLER_ERROR")
-    }
-
-    pub fn is_request_validation_error(&self) -> bool {
-        self.name.as_deref() == Some("REQUEST_VALIDATION_ERROR")
-    }
-
-    pub fn is_internal_error(&self) -> bool {
-        self.name.as_deref() == Some("INTERNAL_ERROR")
-    }
-
-    pub fn cause_name(&self) -> Option<&str> {
-        self.cause.as_ref().map(|c| c.name.as_str())
-    }
-}
-
-impl std::fmt::Display for RpcError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "RPC error {}: {}", self.code, self.message)
-    }
-}
-
-impl std::error::Error for RpcError {}
-
 /// Errors that can occur when making a JSON-RPC call.
 #[derive(Debug, thiserror::Error)]
 pub enum RpcCallError {