Design & Error Code

API Design

1. Path

Nodit Web3 Data API paths follow a common structure as shown below.

/{version}/{protocol}/{network}/{API resource}
//EXAMPLE: /v1/ethereum/mainnet/accounts

version: Specifies the API version. (e.g., v1)
protocol: Specifies the protocol of the target blockchain environment.
network: Specifies the network of the target blockchain environment.
resource: Defines the resource for each API in a hierarchical structure.

2. Listing & Paging

When an API response includes list-type data, the count and items fields are used to distinguish the size and contents of the list. Most list responses support query parameters for pagination. Refer to the table below for parameter details.

Property	Type	Description	Example Value
`count`	Integer	Total number of items.	20
`items`	array:object	Array (list) of response objects.
`page`	Integer	Page number for list pagination. Supported as a query parameter to retrieve results starting from a specific page. Accepts an integer between 1 and 100 (inclusive). Invalid values are ignored. Defaults to 1.	1
`rpp`	Integer	Number of result items to return per page during pagination. Accepts an integer between 1 and 100 (exclusive upper bound). Defaults to 20.	20
`cursor`	string	The cursor parameter is used for pagination and supports navigation between previous and next pages. Providing the cursor value from the previous response in the next request loads the following page of data. If neither `page` nor `cursor` is specified, cursor-based pagination is assumed. This parameter cannot be used together with `page`.

3. Response Format

All Nodit Web3 Data API responses return data wrapped inside an object. Responses that return multiple items include a pagination field.

Key	Value Description
pagination	A value from section 2 (Listing & Paging) that distinguishes the size and contents of the response. Included fields are `count`, `items`, `page`, `rpp`, and `cursor`.

For successful responses (HTTP status code 2XX), the actual response object is returned in the response body in domain response format.

Key	Value Description
data	The result data object for the request.

For non-successful responses, a message field is included in the response along with a code field. It contains a description of the error that occurred.

Key	Value Description
message	A descriptive message explaining the error.

Response examples for both success and failure cases are as follows.

Success Response Example (data)
{
  "rpp": 20,
  "cursor": "eyJibG9ja1RpbWVzdGFtcCI6MTczODI0Nzk5OSwiYmxvY2tOdW1iZXIiOjIxNzM4MDA3LCJ0cmFuc2FjdGlvbkluZGV4IjoyMTV9",
  "range": {
    "fromDate": "2025-01-01T00:00:00.000Z",
    "toDate": "2025-01-31T00:00:00.000Z"
  },
  "items": [
    {
      "transactionHash": "0x7218f7f086b007606b338486808f934d49cede618930207f5a683c091fb7ff49",
      "transactionIndex": "158",
      "blockHash": "0x250d13df765b6ab09d2bee624b7c125d9de15ffbabe032d52eb23b6e2573a099",
      "blockNumber": 21740626,
      "from": "0xD2247Afd5fb3A5c25faD956B2411E39b9F5b7417",
      "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "value": "100000000000000",
      "input": "0x",
      "functionSelector": "0x",
      "nonce": "186",
      "gas": "31500",
      "gasPrice": "1942787348",
      "maxFeePerGas": "2100000000",
      "maxPriorityFeePerGas": "1700000",
      "gasUsed": "21000",
      "cumulativeGasUsed": "14332528",
      "effectiveGasPrice": "1942787348",
      "contractAddress": null,
      "type": "2",
      "status": "1",
      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
      "accessList": [],
      "timestamp": 1738279595
    },
      ...
    {
      "transactionHash": "0x30c0e22cb827af2e9236a85cbccfa2795afbb2d6ae278f7c45cf77bb6a8eaf2b",
      "transactionIndex": "215",
      "blockHash": "0x78d017a72bb2b2c0a908ede50179bae4a4844d7b2f4ff92314fe60902c85ef9d",
      "blockNumber": 21738007,
      "from": "0x5C6d48af40A35B73C489650559D5F2309F7c29C1",
      "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "value": "100000000000000",
      "input": "0x",
      "functionSelector": "0x",
      "nonce": "1",
      "gas": "31500",
      "gasPrice": "3900000000",
      "gasUsed": "21000",
      "cumulativeGasUsed": "25628667",
      "effectiveGasPrice": "3900000000",
      "contractAddress": null,
      "type": "0",
      "status": "1",
      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
      "accessList": [],
      "timestamp": 1738247999
    }
  ]
}

Failure Response Example
{
  "message": "Authentication failed.",
  "code": "AUTHENTICATION_FAILED"
}

Error Codes

When an API request fails, an HTTP status code is returned along with code and message fields in the response body. The code is a string that identifies the cause of the error, and the message contains a detailed description.

Error Response Example
{
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter: { PARAMETER_NAME }"
}

HTTP Code	Error Code	Description
400	`MISSING_REQUIRED_PARAMETER`	A required parameter is missing.
	`INVALID_PARAMETER`	An invalid parameter value was provided.
	`WRONG_RANGE_PARAMETER`	A value outside the allowed query range was provided.
	`DEPRECATED_OPERATION`	A deprecated API was requested.
401	`NO_AUTHENTICATION_FOUND`	No authentication information was included in the request.
401	`AUTHENTICATION_FAILED`	The authentication information is mismatched or invalid.
403	`PERMISSION_DENIED`	Access was blocked by the Domain or Source IP Allowlist security settings.
404	`WRONG_ENDPOINT`	A non-existent API path was requested.
	`NOT_SUPPORTED_CHAIN`	An unsupported chain was requested.
	`RESOURCE_NOT_FOUND`	The requested resource does not exist on the server.
405	`METHOD_NOT_ALLOWED`	The request was made using an unsupported HTTP method.
408	`TIMEOUT`	The request was not processed within the allowed time limit.
409	`RESOURCE_ALREADY_EXISTS`	A duplicate creation request was made for a resource that already exists.
409	`REJECTED`	The request was rejected by the server.
413	`CONTENTS_TOO_LARGE`	The request payload exceeds the maximum allowed size.
414	`TOO_LONG_URI`	The request URI exceeds the maximum allowed length.
429	`TOO_MANY_REQUESTS`	The rate limit has been exceeded.
429	`EXCEEDED_QUOTA_LIMIT`	The quota limit has been exceeded.
500	`INTERNAL_SERVER_ERROR`	An internal server error occurred.
500	`INTERRUPTED`	Processing temporarily failed due to server load.
503	`UNAVAILABLE`	The service is unavailable due to infrastructure downtime or an upgrade.

API Design​

1. Path​

2. Listing & Paging​

3. Response Format​

Error Codes​

API Design

1. Path

2. Listing & Paging

3. Response Format

Error Codes