Error Handling

This document helps you quickly identify and respond to errors that may occur when using the Nodit API. It covers the common error response format and HTTP status codes, followed by resolution steps for frequently encountered errors.

---

Web3 Data API Error Response Format

When an error occurs, the Nodit API returns a consistent JSON structure. Parse the response body and check the code and message fields to determine the cause of the error.

Error Response Format

{
  "code": "ERROR_CODE",
  "message": "Human-readable error description"
}

---

HTTP Status Codes

The Nodit API uses standard HTTP status codes. Because the cause and resolution vary by status code, refer to the table below to handle errors appropriately.

Status Code	Name	Cause	Resolution
400	Bad Request	A request parameter is invalid or missing.	Verify the parameter names, types, and required fields.
401	Unauthorized	The API Key is invalid or missing.	Confirm that a valid API Key is included in the X-API-KEY header.
403	Forbidden	The request is blocked due to insufficient permissions or an access policy.	Review the project permissions and Security settings (e.g., IP/Domain Allowlist).
404	Not Found	The requested resource does not exist.	Verify that the request URL path and parameter values are correct.
405	Method Not Allowed	An unsupported HTTP method was used.	Check the API documentation for the allowed HTTP methods.
408	Request Timeout	The request exceeded the processing time limit.	Reduce the query range (block range, time range, etc.) or optimize the request parameters.
409	Conflict	A resource conflict occurred or the server rejected the request.	Check whether the resource already exists and whether the request state conflicts.
413	Payload Too Large	The request body exceeds the allowed size limit.	Reduce the request size or split the batch request into smaller parts.
414	URI Too Long	The request URI exceeds the allowed length.	Move parameters to the request body or shorten the URI.
429	Too Many Requests	The Rate Limit or usage quota has been exceeded.	Check the Retry-After header and the usage limits for your current plan.
500	Internal Server Error	An internal server error occurred.	Retry after a moment. If the error persists, contact Nodit support.
503	Service Unavailable	The service is temporarily unavailable.	Retry after a moment.

---

Troubleshooting

The following sections cover frequently encountered errors and their resolutions.

401 Unauthorized

This error occurs when the API Key is missing or invalid.

401 Response Example

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Authentication failed"
}

Resolution:

• Confirm that X-API-KEY is correctly included in the request header.
• Verify that the API Key is active in the Nodit Console.
• Confirm that the API Key is associated with the correct project.

Depending on the situation, the NO_AUTHENTICATION_FOUND code may also be returned.

408 Request Timeout

This error occurs when a request exceeds the processing time limit. It commonly appears when querying a wide block range or a large volume of data.

408 Response Example

{
  "code": "TIMEOUT",
  "message": "Request timeout"
}

Resolution:

• Narrow the fromBlock and toBlock range to split the query into smaller intervals.
• Remove unnecessary parameters or add filter conditions to reduce the result size.
• For large data requirements, use pagination (cursor and rpp parameters) to retrieve data in smaller batches.

429 Too Many Requests

This error occurs when the Rate Limit or quota is exceeded. Nodit limits the number of requests that can be processed per second (Throughput) based on the plan, and some plans also enforce periodic usage limits.

429 Response Example

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests"
}

Depending on the situation, the EXCEEDED_QUOTA_LIMIT code may also be returned.

Resolution:

• For a TOO_MANY_REQUESTS response, check the Retry-After value and retry after the specified number of seconds.
• Apply an exponential backoff pattern to progressively increase the interval between retries.
• Batch requests or reduce unnecessary calls to lower the overall request count.
• For an EXCEEDED_QUOTA_LIMIT response, review the usage limits for your current plan.
• If you consistently reach the limit, consider upgrading to a higher-tier plan that offers greater Throughput or usage allowances.

For Rate Limit thresholds by plan, refer to the Rate Limits documentation.

gRPC API Error Response Format

The gRPC API uses the HTTP/2-based gRPC protocol and returns the result of RPC processing in the response trailers. When an error occurs, you can check the grpc-status and grpc-message values to identify the error status code and its cause.

grpc-status: 3
grpc-message: INVALID_ARGUMENT

---

gRPC Status

The Nodit gRPC API uses standard gRPC status codes. Since the cause and the way to respond differ by status code, refer to the table below to handle them appropriately.

gRPC Status	Name	Cause	Resolution
1	CANCELLED	The request was cancelled by the user.	Retry the request.
3	INVALID_ARGUMENT	The request argument is invalid or missing.	Check the argument you entered for typos or missing values.
4	DEADLINE_EXCEEDED	The request processing time was exceeded.	Reduce the query range (block range, time range, etc.) or optimize the request parameters.
5	NOT_FOUND	The requested resource does not exist.	Verify that the request URL path and parameter values are correct.
6	ALREADY_EXISTS	The resource you are trying to create already exists.	Use the existing resource, or check the resource details and create a new one.
7	PERMISSION_DENIED	You do not have permission, or the request was blocked by an access policy.	Check your project permissions and Security settings (IP/Domain Allowlist, etc.).
8	RESOURCE_EXHAUSTED	The Rate Limit or usage limit was exceeded.	Reduce the query range (block range, time range, etc.) or optimize the request parameters.
12	UNIMPLEMENTED	You used an unsupported gRPC method.	Check the allowed HTTP methods in the API documentation.
13	INTERNAL	An internal server error occurred.	Retry after a short while. If the error persists, contact the Nodit support team.
14	UNAVAILABLE	The service is temporarily unavailable.	Retry after a short while.
16	UNAUTHENTICATED	The API Key is invalid or missing.	Verify that a valid API Key is included in the X-API-KEY header.

---

gRPC API Troubleshooting

This section describes how to handle errors from the node gRPC API.

When a node provides a gRPC interface, as with Sui, error information is delivered in the HTTP/2 trailer frame rather than in the HTTP response body. Even when an error occurs, the HTTP status is always 200.

The trailer contains the following three fields.

Field	Description
grpc-status	The gRPC status code
grpc-message	The developer-facing error message
grpc-status-details-bin	A Base64-encoded google.rpc.Status

When grpc-message is empty

In some cases, parsing only grpc-status and grpc-message is not enough to determine the cause. A typical example is a missing required field error under INVALID_ARGUMENT, where grpc-message is returned as an empty string.

grpc-status : 3
grpc-message:

In this case, decode grpc-status-details-bin and check details for the exact error reason.

Decoding example (Go)

grpc-status-details-bin decoding

import (
    "google.golang.org/grpc/status"
    "google.golang.org/genproto/googleapis/rpc/errdetails"
)

st := status.Convert(err)

for _, d := range st.Details() {
    if br, ok := d.(*errdetails.BadRequest); ok {
        for _, v := range br.GetFieldViolations() {
            fmt.Printf("field: %s\n", v.GetField())
            fmt.Printf("reason: %s\n", v.GetReason())
        }
    }
}

The processing works as follows.

1. st.Details() handles the decoding and deserialization of grpc-status-details-bin and returns details.

2. details is an array that can contain any type. Find the BadRequest type among them and iterate over its field_violations.

message BadRequest {
  message FieldViolation {
    string field = 1;             
    string description = 2;       
    string reason = 3;            
    LocalizedMessage localized_message = 4;
  }
  repeated FieldViolation field_violations = 1;
}

3. By checking the field and reason values in field_violations, you can identify the cause of the error and the field responsible for it, as shown below, and build your error-handling logic based on this.

field: transaction
reason: FIELD_MISSING

---