Skip to content

Commit d63a10c

Browse files
matiasbenaryGuillermo Alejandro Gallardo Diez
matiasbenary
and
Guillermo Alejandro Gallardo Diez
authored
Update rpc (#2704)
* wip - cleaning up and simplifying MDC files * wip remove components * wip modify rpc * feat: refactor RPC views * feat: refactor RPC views * fix: build * chore: remove unnecesary sections * wip update error table * feat: update error handler --------- Co-authored-by: Guillermo Alejandro Gallardo Diez <[email protected]>
1 parent 22382f2 commit d63a10c

File tree

196 files changed

+4330
-7534
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

196 files changed

+4330
-7534
lines changed

‎docs/api/rpc/access-keys.md‎

Lines changed: 480 additions & 9 deletions
Large diffs are not rendered by default.

‎docs/api/rpc/block-chunk.md‎

Lines changed: 772 additions & 6 deletions
Large diffs are not rendered by default.

‎docs/api/rpc/contracts.md‎

Lines changed: 792 additions & 14 deletions
Large diffs are not rendered by default.

‎docs/api/rpc/errors.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
id: errors
3+
title: RPC Errors
4+
description: "Understand common RPC errors and how to handle them."
5+
---
6+
7+
Understand common RPC errors and how to handle them.
8+
9+
## What Could Go Wrong?
10+
11+
When API request fails, RPC server returns a structured error response with a
12+
limited number of well-defined error variants, so client code can exhaustively
13+
handle all the possible error cases. Our JSON-RPC errors follow
14+
[verror](https://github.com/joyent/node-verror) convention for structuring
15+
the error response:
16+
17+
```json
18+
{
19+
"error": {
20+
"name": <ERROR_TYPE>,
21+
"cause": {
22+
"info": {..},
23+
"name": <ERROR_CAUSE>
24+
},
25+
"code": -32000,
26+
"data": String,
27+
"message": "Server error"
28+
},
29+
"id": "dontcare",
30+
"jsonrpc": "2.0"
31+
}
32+
```
33+
34+
> **Heads up**
35+
>
36+
> The fields `code`, `data`, and `message` in the structure above are considered
37+
> legacy ones and might be deprecated in the future. Please, don't rely on them.
38+
39+
Here is the exhaustive list of the error variants that can be returned, organized by HTTP status code:
40+
41+
## 200 - Successful Response with Error Data
42+
43+
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.
44+
45+
**ERROR_TYPE:** `HANDLER_ERROR`
46+
47+
### General Errors
48+
49+
These are general errors that can occur across different API endpoints.
50+
51+
| ERROR_CAUSE | Reason | Solution |
52+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
53+
| 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) |
54+
| INVALID_ACCOUNT | The requested `account_id` is invalid | • Provide a valid `account_id` |
55+
| 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 |
56+
| 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 |
57+
| 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 |
58+
| 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 |
59+
60+
### Access Keys
61+
62+
Errors specific to [Access Keys API](/api/rpc/access-keys).
63+
64+
| ERROR_CAUSE | Reason | Solution |
65+
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
66+
| 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 |
67+
68+
### Accounts / Contracts
69+
70+
Errors specific to [Accounts / Contracts API](/api/rpc/contracts).
71+
72+
| ERROR_CAUSE | Reason | Solution |
73+
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
74+
| 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 |
75+
| 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 |
76+
| 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 |
77+
78+
### Block / Chunk
79+
80+
Errors specific to [Block / Chunk API](/api/rpc/block-chunk).
81+
82+
| ERROR_CAUSE | Reason | Solution |
83+
| ---------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
84+
| 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 |
85+
| INVALID_SHARD_ID | The provided shard ID is invalid or doesn't exist | • Provide a valid shard ID within the network's shard range |
86+
87+
### Network
88+
89+
Errors specific to [Network API](/api/rpc/network).
90+
91+
| ERROR_CAUSE | Reason | Solution |
92+
| ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93+
| 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 |
94+
95+
### Transactions
96+
97+
Errors specific to [Transactions API](/api/rpc/transactions).
98+
99+
| ERROR_CAUSE | Reason | Solution |
100+
| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
101+
| 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 |
102+
| 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 |
103+
104+
## 400 - Bad Request
105+
106+
These errors indicate that the request was malformed or contains invalid parameters that prevent the server from processing it.
107+
108+
**ERROR_TYPE:** `REQUEST_VALIDATION_ERROR`
109+
110+
| ERROR_CAUSE | Reason | Solution |
111+
| ----------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
112+
| 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 |
113+
114+
## 408 - Request Timeout
115+
116+
These errors occur when a request takes too long to process and times out before completion.
117+
118+
**ERROR_TYPE:** `REQUEST_VALIDATION_ERROR`
119+
120+
### Transaction Timeouts
121+
122+
Errors specific to [Transactions API](/api/rpc/transactions) that occur due to timeout conditions.
123+
124+
| ERROR_CAUSE | Reason | Solution |
125+
| ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
126+
| 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) |
127+
128+
## 500 - Internal Server Error
129+
130+
These errors indicate that something went wrong on the server side, typically due to internal issues or server overload.
131+
132+
**ERROR_TYPE:** `INTERNAL_ERROR`
133+
134+
| ERROR_CAUSE | Reason | Solution |
135+
| -------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
136+
| 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 |

‎docs/api/rpc/gas.md‎

Lines changed: 146 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,155 @@
22
id: gas
33
title: Gas
44
description: "Query gas prices for specific blocks or hashes using the NEAR RPC API."
5+
hide_table_of_contents: true
56
---
67

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

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

1116
---
12-
<GasPrice />
13-
---
17+
18+
## Quick Reference
19+
20+
| Parameter | Type | Description |
21+
| --- | --- | --- |
22+
| `block_height` | `number` | Specific block height to query gas price for |
23+
| `block_hash` | `string` | Specific block hash to query gas price for |
24+
| `null` | `null` | Returns gas price for the latest block |
25+
26+
## Gas Price {#gas-price}
27+
28+
<SplitLayoutContainer>
29+
<SplitLayoutLeft title="Description">
30+
Returns gas price for a specific `block_height` or `block_hash`.
31+
32+
- Using `[null]` will return the most recent block's gas price.
33+
34+
- **method**: `gas_price`
35+
- **params**: `[block_height]`, `["block_hash"]`, or `[null]`
36+
</SplitLayoutLeft>
37+
<SplitLayoutRight title="Example">
38+
**`null` example:**
39+
40+
<Tabs groupId="code-tabs">
41+
<TabItem value="json" label="JSON" default>
42+
```json
43+
{
44+
"jsonrpc": "2.0",
45+
"id": "dontcare",
46+
"method": "gas_price",
47+
"params": [null]
48+
}
49+
```
50+
</TabItem>
51+
<TabItem value="js" label="JavaScript">
52+
```js
53+
const response = await near.connection.provider.gasPrice(null);
54+
```
55+
</TabItem>
56+
<TabItem value="http" label="HTTPie">
57+
```bash
58+
http POST https://rpc.testnet.near.org \
59+
jsonrpc=2.0 \
60+
id=dontcare \
61+
method=gas_price \
62+
params:='[null]'
63+
```
64+
</TabItem>
65+
<TabItem value="Lantstool" label={<LantstoolLabel />}>
66+
<TryOutOnLantstool path="docs/5.api/rpc/gas/get-latest-gas-price.json" />
67+
</TabItem>
68+
</Tabs>
69+
70+
**`block_height` example:**
71+
72+
<Tabs groupId="code-tabs">
73+
<TabItem value="json" label="JSON" default>
74+
```json
75+
{
76+
"jsonrpc": "2.0",
77+
"id": "dontcare",
78+
"method": "gas_price",
79+
"params": [187310138]
80+
}
81+
```
82+
</TabItem>
83+
<TabItem value="js" label="JavaScript">
84+
```js
85+
const response = await near.connection.provider.gasPrice(187310138);
86+
```
87+
</TabItem>
88+
<TabItem value="http" label="HTTPie">
89+
```bash
90+
http POST https://archival-rpc.testnet.near.org \
91+
jsonrpc=2.0 \
92+
id=dontcare \
93+
method=gas_price \
94+
params:='[187310138]'
95+
```
96+
</TabItem>
97+
<TabItem value="Lantstool" label={<LantstoolLabel />}>
98+
<TryOutOnLantstool path="docs/5.api/rpc/gas/get-gas-price-by-block-height.json" />
99+
</TabItem>
100+
</Tabs>
101+
102+
**`block_hash` example:**
103+
104+
<Tabs groupId="code-tabs">
105+
<TabItem value="json" label="JSON" default>
106+
```json
107+
{
108+
"jsonrpc": "2.0",
109+
"id": "dontcare",
110+
"method": "gas_price",
111+
"params": ["6RWmTYhXCzjMjoY3Mz1rfFcnBm8E6XeDDbFEPUA4sv1w"]
112+
}
113+
```
114+
</TabItem>
115+
<TabItem value="js" label="JavaScript">
116+
```js
117+
const response = await near.connection.provider.gasPrice(
118+
'6RWmTYhXCzjMjoY3Mz1rfFcnBm8E6XeDDbFEPUA4sv1w',
119+
);
120+
```
121+
</TabItem>
122+
<TabItem value="http" label="HTTPie">
123+
```bash
124+
http POST https://archival-rpc.testnet.near.org \
125+
jsonrpc=2.0 \
126+
id=dontcare \
127+
method=gas_price \
128+
params:='["6RWmTYhXCzjMjoY3Mz1rfFcnBm8E6XeDDbFEPUA4sv1w"]'
129+
```
130+
</TabItem>
131+
<TabItem value="Lantstool" label={<LantstoolLabel />}>
132+
<TryOutOnLantstool path="docs/5.api/rpc/gas/get-gas-price-by-block-hash.json" />
133+
</TabItem>
134+
</Tabs>
135+
</SplitLayoutRight>
136+
</SplitLayoutContainer>
137+
138+
<details>
139+
<summary>Example response:</summary>
140+
141+
```json
142+
{
143+
"jsonrpc": "2.0",
144+
"id": "dontcare",
145+
"result": {
146+
"gas_price": "100000000"
147+
}
148+
}
149+
```
150+
</details>
151+
<details>
152+
<summary>Error handling:</summary>
153+
154+
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.
155+
156+
</details>

0 commit comments

Comments
 (0)