RPC API Design & Error Codes

API Design

1. Endpoint

The Nodit RPC API endpoint follows the structure below.

https://{chain}-{network}.nodit.io
// Example: https://ethereum-mainnet.nodit.io

chain: Specifies the target blockchain. (e.g., ethereum, polygon, base)
network: Specifies the network of the target blockchain. (e.g., mainnet, sepolia)

2. Request Format

Nodit RPC API follows the JSON-RPC 2.0 specification.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_blockNumber",
  "params": []
}

jsonrpc: The JSON-RPC version. Must always be "2.0".
id: The request identifier. Returned with the same value in the response.
method: The name of the RPC method to invoke.
params: An array of parameters to pass to the method.

3. Authentication

All requests require an X-API-KEY header. You can issue an API Key from the Nodit Console.

curl -X POST https://ethereum-mainnet.nodit.io \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: {your-api-key}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Wallet services such as MetaMask do not support setting arbitrary HTTP headers when configuring a Custom RPC endpoint. For RPC endpoints used directly in a wallet, include the API Key in the RPC URL instead of an HTTP header.

curl -X POST https://ethereum-mainnet.nodit.io/{your-api-key} \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

4. Response Format

All RPC API responses follow the same structure as the response object defined in the JSON-RPC 2.0 protocol. The fields returned are described below.

Field	Description
`jsonrpc`	The version of the JSON-RPC protocol. Always included regardless of whether the RPC API call succeeds or fails.
`id`	An identifier used to match a response to a specific request. Must match the `id` provided in the request body. Always included regardless of whether the RPC API call succeeds or fails.
`result`	The field that returns the result of the RPC API request.
`error`	The field returned when an error occurs in the JSON-RPC protocol. Contains fields such as `code`, `message`, and `data` to describe the reason for the error.

Error Codes

JSON-RPC expresses the result of a request through the result or error field in the response body, not through HTTP status codes. As a result, even if the HTTP request is delivered successfully and a JSON-RPC response is returned, the HTTP status code may be 200 OK even when the requested method fails to execute.

When using the RPC API, do not determine the success of a request based solely on the HTTP status code. Check whether the error field is present in the response body. If an error field is included, handle the error based on the error.code, error.message, and error.data values.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  }
}

Code	Message	Description
-32700	Parse error	Invalid JSON was received.
-32600	Invalid Request	The JSON object is not a valid Request object.
-32601	Method not found	The method does not exist or is not available.
-32602	Invalid params	Invalid method parameters.
-32603	Internal error	An internal JSON-RPC error occurred.

HTTP Error Codes

Code	Description
400	A malformed request was sent.
401	The API Key is missing or invalid.
403	Access was blocked by the domain or IP allowlist security settings.
429	The request rate limit has been exceeded.
500	An internal server error occurred.