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.

---

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.