Skip to content

Update rpc #2704

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Aug 25, 2025
Merged

Update rpc #2704

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
ac16252
wip - cleaning up and simplifying MDC files
matiasbenary Aug 12, 2025
a938992
wip remove components
matiasbenary Aug 12, 2025
8d3f265
wip modify rpc
matiasbenary Aug 14, 2025
225a814
feat: refactor RPC views
matiasbenary Aug 14, 2025
20280bb
feat: refactor RPC views
matiasbenary Aug 15, 2025
a23efba
fix: build
matiasbenary Aug 15, 2025
09989e8
Merge branch 'master' into update-rpc
matiasbenary Aug 15, 2025
b1fbedd
merge with master
matiasbenary Aug 21, 2025
7a3afbc
chore: remove unnecesary sections
Aug 21, 2025
6a01e67
wip update error table
matiasbenary Aug 21, 2025
d6a53c5
feat: update error handler
matiasbenary Aug 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
489 changes: 480 additions & 9 deletions docs/api/rpc/access-keys.md
View file
Open in desktop

Large diffs are not rendered by default.

778 changes: 772 additions & 6 deletions docs/api/rpc/block-chunk.md
View file
Open in desktop

Large diffs are not rendered by default.

806 changes: 792 additions & 14 deletions docs/api/rpc/contracts.md
View file
Open in desktop

Large diffs are not rendered by default.

136 changes: 136 additions & 0 deletions docs/api/rpc/errors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
---
id: errors
title: RPC Errors
description: "Understand common RPC errors and how to handle them."
---

Understand common RPC errors and how to handle them.

## What Could Go Wrong?

When API request fails, RPC server returns a structured error response with a
limited number of well-defined error variants, so client code can exhaustively
handle all the possible error cases. Our JSON-RPC errors follow
[verror](https://github.com/joyent/node-verror) convention for structuring
the error response:

```json
{
"error": {
"name": <ERROR_TYPE>,
"cause": {
"info": {..},
"name": <ERROR_CAUSE>
},
"code": -32000,
"data": String,
"message": "Server error"
},
"id": "dontcare",
"jsonrpc": "2.0"
}
```

> **Heads up**
>
> The fields `code`, `data`, and `message` in the structure above are considered
> legacy ones and might be deprecated in the future. Please, don't rely on them.

Here is the exhaustive list of the error variants that can be returned, organized by HTTP status code:

## 200 - Successful Response with Error Data

These errors occur when the request was processed successfully but the requested data could not be retrieved or an operation could not be completed due to various blockchain-related conditions.

**ERROR_TYPE:** `HANDLER_ERROR`

### General Errors

These are general errors that can occur across different API endpoints.

| ERROR_CAUSE | Reason | Solution |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| UNKNOWN_BLOCK | The requested block has not been produced yet or it has been garbage-collected (cleaned up to save space on the RPC node) | • Check that the requested block is legit <br/>• If the block had been produced more than 5 epochs ago, try to send your request to [an archival node](https://near-nodes.io/intro/node-types#archival-node) |
| INVALID_ACCOUNT | The requested `account_id` is invalid | • Provide a valid `account_id` |
| UNKNOWN_ACCOUNT | The requested `account_id` has not been found while viewing since the account has not been created or has been already deleted | • Check the `account_id` <br/>• Specify a different block or retry if you request the latest state |
| UNAVAILABLE_SHARD | The node was unable to found the requested data because it does not track the shard where data is present | • Send a request to a different node which might track the shard |
| NO_SYNCED_BLOCKS | The node is still syncing and the requested block is not in the database yet | • Wait until the node finish syncing <br/>• Send a request to a different node which is synced |
| NOT_SYNCED_YET | The node is still syncing and the requested block is not in the database yet | • Wait until the node finish syncing <br/>• Send a request to a different node which is |

### Access Keys

Errors specific to [Access Keys API](/api/rpc/access-keys).

| ERROR_CAUSE | Reason | Solution |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| UNKNOWN_ACCESS_KEY | The requested `public_key` has not been found while viewing since the public key has not been created or has been already deleted | • Check the `public_key` <br/>• Specify a different block or retry if you request the latest state |

### Accounts / Contracts

Errors specific to [Accounts / Contracts API](/api/rpc/contracts).

| ERROR_CAUSE | Reason | Solution |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NO_CONTRACT_CODE | The account does not have any `contract` deployed on it | • Use different account <br/>• Specify a different block or retry if you request the latest state |
| TOO_LARGE_CONTRACT_STATE | The requested contract state is too large to be returned from this node (the default limit is 50kb of state size) | • Send the request to a node with larger limits in order to view the requested state <br/>• Spin up your own node where you can increase the limits to view state |
| CONTRACT_EXECUTION_ERROR | The execution of the view function call failed (crashed, run out of the default 200 TGas limit, etc) | • Check `error.cause.info` for more details |

### Block / Chunk

Errors specific to [Block / Chunk API](/api/rpc/block-chunk).

| ERROR_CAUSE | Reason | Solution |
| ---------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| UNKNOWN_CHUNK | The requested chunk is not available or has been garbage-collected | • Check chunk ID validity <br/>• Try an archival node for older chunks |
| INVALID_SHARD_ID | The provided shard ID is invalid or doesn't exist | • Provide a valid shard ID within the network's shard range |

### Network

Errors specific to [Network API](/api/rpc/network).

| ERROR_CAUSE | Reason | Solution |
| ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UNKNOWN_EPOCH | An epoch for the provided block can't be found in a database | • Check that the requested block is legit <br/>• If the block had been produced more than 5 epochs ago, try to send your request to an archival node <br/>•Check that the requested block is the last block of some epoch |

### Transactions

Errors specific to [Transactions API](/api/rpc/transactions).

| ERROR_CAUSE | Reason | Solution |
| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| INVALID_TRANSACTION | An error happened during transaction execution | • See `error.cause.info` for details, likely a field in the transaction was invalid <br/>•If `error.cause.info` is `ShardCongested`, resubmit the identical transaction after a delay. (Consider adding a priority fee once [NEP-541](https://github.com/near/NEPs/pull/541) is released.) <br/>• If `error.cause.info` is `ShardStuck`, you may also resubmit the identical transaction after a delay |
| UNKNOWN_RECEIPT | The receipt with the given `receipt_id` was never observed on the node | • Check the provided `receipt_id` is correct <br/>• Send a request on a different node |

## 400 - Bad Request

These errors indicate that the request was malformed or contains invalid parameters that prevent the server from processing it.

**ERROR_TYPE:** `REQUEST_VALIDATION_ERROR`

| ERROR_CAUSE | Reason | Solution |
| ----------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| PARSE_ERROR | Passed arguments can't be parsed by JSON RPC server (missing arguments, wrong format, etc.) | • Check the arguments passed and pass the correct ones <br/>• Check `error.cause.info` for more details |

## 408 - Request Timeout

These errors occur when a request takes too long to process and times out before completion.

**ERROR_TYPE:** `REQUEST_VALIDATION_ERROR`

### Transaction Timeouts

Errors specific to [Transactions API](/api/rpc/transactions) that occur due to timeout conditions.

| ERROR_CAUSE | Reason | Solution |
| ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TIMEOUT_ERROR | Transaction was routed, but has not been recorded on chain in 10 seconds. | • Resubmit the request with the identical transaction (in NEAR Protocol unique transactions apply exactly once, so if the previously sent transaction gets applied, this request will just return the known result, otherwise, it will route the transaction to the chain once again) <br/>• Check that your transaction is valid <br/>• Check that the signer account id has enough tokens to cover the transaction fees (keep in mind that some tokens on each account are locked to cover the storage cost) |

## 500 - Internal Server Error

These errors indicate that something went wrong on the server side, typically due to internal issues or server overload.

**ERROR_TYPE:** `INTERNAL_ERROR`

| ERROR_CAUSE | Reason | Solution |
| -------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| INTERNAL_ERROR | Something went wrong with the node itself or overloaded | • Try again later <br/>• Send a request to a different node <br/>• Check `error.cause.info` for more details |
149 changes: 146 additions & 3 deletions docs/api/rpc/gas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,155 @@
id: gas
title: Gas
description: "Query gas prices for specific blocks or hashes using the NEAR RPC API."
hide_table_of_contents: true
---

import GasPrice from '@site/src/components/docs/api/rpc/gas/gas-price/index.mdx';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import { TryOutOnLantstool } from '@site/src/components/lantstool/TryOutOnLantstool';
import { LantstoolLabel } from '@site/src/components/lantstool/LantstoolLabel/LantstoolLabel';
import { SplitLayoutContainer, SplitLayoutLeft, SplitLayoutRight } from '@site/src/components/SplitLayout';

The RPC API enables you to query the gas price for a specific block or hash.

---
<GasPrice />
---

## Quick Reference

| Parameter | Type | Description |
| --- | --- | --- |
| `block_height` | `number` | Specific block height to query gas price for |
| `block_hash` | `string` | Specific block hash to query gas price for |
| `null` | `null` | Returns gas price for the latest block |

## Gas Price {#gas-price}

<SplitLayoutContainer>
<SplitLayoutLeft title="Description">
Returns gas price for a specific `block_height` or `block_hash`.

- Using `[null]` will return the most recent block's gas price.

- **method**: `gas_price`
- **params**: `[block_height]`, `["block_hash"]`, or `[null]`
</SplitLayoutLeft>
<SplitLayoutRight title="Example">
**`null` example:**

<Tabs groupId="code-tabs">
<TabItem value="json" label="JSON" default>
```json
{
"jsonrpc": "2.0",
"id": "dontcare",
"method": "gas_price",
"params": [null]
}
```
</TabItem>
<TabItem value="js" label="JavaScript">
```js
const response = await near.connection.provider.gasPrice(null);
```
</TabItem>
<TabItem value="http" label="HTTPie">
```bash
http POST https://rpc.testnet.near.org \
jsonrpc=2.0 \
id=dontcare \
method=gas_price \
params:='[null]'
```
</TabItem>
<TabItem value="Lantstool" label={<LantstoolLabel />}>
<TryOutOnLantstool path="docs/5.api/rpc/gas/get-latest-gas-price.json" />
</TabItem>
</Tabs>

**`block_height` example:**

<Tabs groupId="code-tabs">
<TabItem value="json" label="JSON" default>
```json
{
"jsonrpc": "2.0",
"id": "dontcare",
"method": "gas_price",
"params": [187310138]
}
```
</TabItem>
<TabItem value="js" label="JavaScript">
```js
const response = await near.connection.provider.gasPrice(187310138);
```
</TabItem>
<TabItem value="http" label="HTTPie">
```bash
http POST https://archival-rpc.testnet.near.org \
jsonrpc=2.0 \
id=dontcare \
method=gas_price \
params:='[187310138]'
```
</TabItem>
<TabItem value="Lantstool" label={<LantstoolLabel />}>
<TryOutOnLantstool path="docs/5.api/rpc/gas/get-gas-price-by-block-height.json" />
</TabItem>
</Tabs>

**`block_hash` example:**

<Tabs groupId="code-tabs">
<TabItem value="json" label="JSON" default>
```json
{
"jsonrpc": "2.0",
"id": "dontcare",
"method": "gas_price",
"params": ["6RWmTYhXCzjMjoY3Mz1rfFcnBm8E6XeDDbFEPUA4sv1w"]
}
```
</TabItem>
<TabItem value="js" label="JavaScript">
```js
const response = await near.connection.provider.gasPrice(
'6RWmTYhXCzjMjoY3Mz1rfFcnBm8E6XeDDbFEPUA4sv1w',
);
```
</TabItem>
<TabItem value="http" label="HTTPie">
```bash
http POST https://archival-rpc.testnet.near.org \
jsonrpc=2.0 \
id=dontcare \
method=gas_price \
params:='["6RWmTYhXCzjMjoY3Mz1rfFcnBm8E6XeDDbFEPUA4sv1w"]'
```
</TabItem>
<TabItem value="Lantstool" label={<LantstoolLabel />}>
<TryOutOnLantstool path="docs/5.api/rpc/gas/get-gas-price-by-block-hash.json" />
</TabItem>
</Tabs>
</SplitLayoutRight>
</SplitLayoutContainer>

<details>
<summary>Example response:</summary>

```json
{
"jsonrpc": "2.0",
"id": "dontcare",
"result": {
"gas_price": "100000000"
}
}
```
</details>
<details>
<summary>Error handling:</summary>

When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.

</details>
Loading
Loading