Design & Error Codes

---

API Design

1. Path

The Nodit Multichain API path is structured as follows.

/{version}/multichain/{API resource}
//EXAMPLE: /v1/multichain/lookupEntities

• version: API version (e.g. v1).
• multichain: Fixed segment indicating the Multichain API endpoint.
• resource: The part where each API's resource is defined; hierarchical.

2. Response Format

All Multichain API responses are returned as objects. For successful responses (HTTP 2xx), the response body contains the actual response object in domain form.

Key	Value Description
data	Result data object for the request.

For non-success responses, a message field is included together with code, describing the error.

Key	Value Description
message	Error description message.

Response examples for success and failure cases are shown below.

3. Error Response Format

When an error occurs, the response is returned in the format below. code and message vary by error type; see Error Code Specification for code details.

Error Code Specification

code	HTTP Status Code	Description
SUCCESS	200 OK	Success response
SUCCESS	201 Created	Success (resource created)
MISSING_REQUIRED_PARAMETER	400 Bad Request	A required parameter is missing. [Example Cases] Required field missing in Path, Query, or Body
INVALID_PARAMETER	400 Bad Request	Invalid value provided for a parameter. [Example Cases] Value does not match the specified parameter format Empty value passed for a parameter Value exceeds the maximum allowed length Invalid date/time format Parameter does not follow the defined encoding scheme Parameter value does not match the required format Incompatible parameters used together
WRONG_RANGE_PARAMETER	400 Bad Request	A parameter that specifies the query range has a value outside the allowed range. [Example Cases] Request exceeds the maximum query date in a statistics API Request for data before the reference date Request for a non-existent data range
DEPRECATED_OPERATION	400 Bad Request	Request to a deprecated API or resource. [Example Cases] Request to an older API version that is no longer supported after an update
NO_AUTHENTICATION_FOUND	401 Unauthorized	Authentication info is present in the request but is invalid or the account does not exist. [Example Cases] Auth in path or header has expired Auth in path or header belongs to a different account
AUTHENTICATION_FAILED	401 Unauthorized	No authentication information in the request. [Example Cases] No auth provided in path or header
PERMISSION_DENIED	403 Forbidden	Authenticated but access to the resource is not authorized. [Example Cases] Request exceeds the permissions of the provided credentials
WRONG_ENDPOINT	404 Not Found	The requested API path does not exist. [Example Cases] Invalid API path Non-existent API version Request to an API that has been removed or changed on the server
NOT_SUPPORTED_CHAIN	404 Not Found	Request to a service path that is not supported on the requested chain. [Example Cases] The chain specified in the path parameter {protocol} is not supported for this path
RESOURCE_NOT_FOUND	404 Not Found	The requested resource does not exist on the server. [Example Cases] Request for data that does not exist on the server Request for a non-existent file or resource Request using an invalid ID or key
METHOD_NOT_ALLOWED	405 Method Not Allowed	Request using a disallowed HTTP method. [Example Cases] Valid HTTP method but not supported for the requested API Invalid HTTP method used
TIMEOUT	408 Request Timeout	The call did not complete within the allowed time, or exceeded the time limit set by the WAS controller. [Example Cases] RPC call to the chain for transaction receipt did not complete within 5 seconds; after 3 retries, TIMEOUT is returned to the client When calling Elasticsearch, receipt lookup did not complete within 5 seconds
RESOURCE_ALREADY_EXISTS	409 Conflict	Duplicate create request for an existing resource. [Example Cases] Attempt to create a resource that cannot be duplicated Create request with an identifier that already exists as a key
REJECTED	409 Conflict	The request was rejected by the server.
CONTENTS_TOO_LARGE	413 Payload Too Large	Request payload exceeds the maximum set by the server.
TOO_LONG_URI	414 URI Too Long	Client request URI exceeds the maximum length the server can handle.
TOO_MANY_REQUESTS	429 Too Many Request	Rate limit exceeded. [Example Cases] Per-second or per-minute Compute Unit limit exceeded Per-second or per-minute bytes size limit exceeded Per-second or per-minute request limit exceeded
EXCEEDED_QUOTA_LIMIT	429 Too many request	Quota limit exceeded. [Example Cases] Monthly usage from the user's plan has been exceeded
INTERNAL_SERVER_ERROR	500 Internal Server Error	Internal server error. [Example Cases] Unhandled runtime error Any internal error outside the domain context (e.g. infrastructure such as DB, storage, queue, cache, or external service calls)
INTERRUPTED	500 Internal Server Error	Temporary failure processing a specific client request while handling multiple requests. May indicate server load.
UNAVAILABLE	503 Service Unavailable	Server cannot provide the service (e.g. infrastructure down or upgrade with service interruption).