Design & Error Codes

---

API Design

1. Path

All Multichain API paths follow the common structure below.

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

• version: Specifies the API version. (e.g., v1)
• multichain: A fixed segment indicating that the endpoint belongs to the Multichain API.
• resource: Defines the resource for each API, organized in a hierarchical structure.

2. Response Format

All Multichain API responses are returned as objects. For successful responses (HTTP status code 2XX), the actual response object is returned inside the response body as a domain response.

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

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

Key	Value Description
message	A description message for the error.

The following shows example responses for both success and failure cases.

3. Error Response Format

When an error occurs, the response is returned in the format below. The code and message values vary depending on the type of error. Refer to the Error Code Specification below for details on code values.

Error Code Specification

code	HTTP Status Code	Description
SUCCESS	200 OK	Successful response
SUCCESS	201 Created	Successfully processed (new resource created)
MISSING_REQUIRED_PARAMETER	400 Bad Request	A required parameter is missing. [Example Cases] A required field is missing from Path, Query, or Body parameters
INVALID_PARAMETER	400 Bad Request	An invalid value was provided for a parameter. [Example Casess] A value that violates the expected format of the parameter was provided An empty value was passed to a parameter A value exceeding the maximum allowed length was provided An invalid date/time format was provided A parameter was provided without applying the required encoding scheme A parameter value that does not conform to the expected format was provided Incompatible parameters were used together
WRONG_RANGE_PARAMETER	400 Bad Request	A value outside the allowed range was provided for a range-specifying parameter. [Example Cases] A statistics API request exceeded the maximum allowed query date range A request was made for data prior to the reference date A request was made for a data range that does not exist
DEPRECATED_OPERATION	400 Bad Request	A request was made to a deprecated API or resource. [Example Cases] A request was made to a previous version of an API that is no longer supported due to a version update
NO_AUTHENTICATION_FOUND	401 Unauthorized	Authentication information is present in the request but does not match, or the account does not exist. [Example Cases] Authentication information is included in the path or header but has expired Authentication information is included in the path or header but belongs to a different account
AUTHENTICATION_FAILED	401 Unauthorized	No authentication information is included in the request. [Example Cases] No authentication information was provided in the path or header
PERMISSION_DENIED	403 Forbidden	Authentication succeeded but access to an unauthorized resource was attempted. [Example Cases] A request was made without the required permissions for the authenticated credentials
WRONG_ENDPOINT	404 Not Found	The requested API path does not exist. [Example Cases] An incorrect API path was requested A non-existent API version was requested An API that has been removed or changed on the server was called
NOT_SUPPORTED_CHAIN	404 Not Found	A service path not supported by the requested chain was requested. [Example Cases] The chain specified in the {protocol} path parameter field is not supported for the functionality of that path
RESOURCE_NOT_FOUND	404 Not Found	The requested resource does not exist on the server. [Example Cases] A request was made for data that does not exist on the server A request was made for a file or resource that does not exist Data was requested using an invalid ID or key
METHOD_NOT_ALLOWED	405 Method Not Allowed	A request was made using a disallowed HTTP method. [Example Cases] A valid HTTP method type was used but is not supported by the requested API A request was made using an invalid HTTP method type
TIMEOUT	408 Request Timeout	The call did not complete within the allowed time, or the time limit set by the WAS controller was exceeded. [Example Cases] An RPC call to the chain for retrieving a transaction receipt did not complete within 5 seconds, including 3 retries — a final TIMEOUT error is returned to the client after all attempts fail. An Elasticsearch service call for a receipt query did not complete within 5 seconds
RESOURCE_ALREADY_EXISTS	409 Conflict	A duplicate creation request was made for an already existing resource. [Example Cases] A duplicate creation attempt was made for a resource that cannot be duplicated A creation request was made using 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	The payload exceeds the maximum size configured on the server
TOO_LONG_URI	414 URI Too Long	The client request exceeds the maximum URI length that the server can process.
TOO_MANY_REQUESTS	429 Too Many Request	The allowed rate limit was exceeded. [Example Cases] A per-second or per-minute Compute Unit (CU) limit applies A per-second or per-minute bytes size limit applies A per-second or per-minute requests limit applies
EXCEEDED_QUOTA_LIMIT	429 Too many request	The allowed quota limit was exceeded. [Example Cases] The monthly usage included in the user's subscription plan was exceeded
INTERNAL_SERVER_ERROR	500 Internal Server Error	Internal server error. [Example Cases] An unhandled runtime error occurred Any internal error occurring outside the domain context, such as infrastructure (DB, storage, queue, cache, etc.) or external service calls
INTERRUPTED	500 Internal Server Error	Processing temporarily failed for a specific client's request while handling multiple requests. This can be attributed to an error caused by server load.
UNAVAILABLE	503 Service Unavailable	The server is unable to provide service. This error may be returned due to infrastructure downtime or an upgrade involving a service interruption.