Design & Error Codes

API Design

1. Path

Nodit Multichain API의 Path는 공통적으로 아래와 같이 구성됩니다.

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

version: API의 버전을 명시합니다. (예시) v1
multichain: Multichain API 엔드포인트임을 나타내는 고정 세그먼트입니다.
resource: 각 API의 리소스가 정의되는 파트로, 계층 구조로 구성됩니다.

2. Response Format

모든 Multichain API의 응답은 Object 형태로 반환되며, 정상 응답(HTTP 상태코드가 2XX인 경우)의 경우 응답 Body 내부에 실제 응답 객체가 도메인 응답의 형태로 반환됩니다.

Key	Value Description
data	요청에 대한 결과 응답 data 객체.

정상 응답이 아닌 경우, message필드가 code필드와 함께 응답 내에 포함됩니다. 발생한 오류에 대한 설명을 포함합니다.

Key	Value Description
message	오류에 대한 설명 메세지.

성공과 실패 각 케이스에 대한 응답 예시는 다음과 같습니다.

3. Error Response Format

오류가 발생한 경우 응답은 아래와 같은 형식으로 반환됩니다. code와 message는 발생한 에러 타입에 따라 다른 값으로 반환되며, code 명세에 대해서는 아래 Error Code Specification을 참고하세요.

Error Code Specification

`code`	HTTP Status Code	Description
SUCCESS	200 OK	정상 응답
SUCCESS	201 Created	정상 처리 (신규 생성)
MISSING_REQUIRED_PARAMETER	400 Bad Request	필수 인자가 누락된 경우. [Example Cases] Path, Query, 또는 Body parameter 중 필수 필드 누락
INVALID_PARAMETER	400 Bad Request	인자에 잘못된 값을 입력한 경우. [Example Casess] 지정된 인자의 형식과 위배되는 값이 입력된 경우 인자에 빈 값을 전달한 경우 허용되는 최대 길이를 초과하는 값을 전달한 경우 유효하지 않은 날짜/시간 형식을 입력된 경우 정의된 인코딩 스킴을 적용하지 않은 인자가 입력된 경우 포맷에 맞지 않는 인자 값을 입력한 경우 호환되지 않는 파라미터를 함께 사용한 경우
WRONG_RANGE_PARAMETER	400 Bad Request	조회 범위를 지정하는 인자에 범위 밖의 값을 입력한 경우. [Example Cases] 통계 API에서 최대 조회 일자를 초과하여 요청한 경우 기준일 이전 데이터를 요청한 경우 존재하지 않는 데이터 범위에 대해 요청한 경우
DEPRECATED_OPERATION	400 Bad Request	Deprecate된 API 및 리소스에 대한 요청한 경우. [Example Cases] API 버전이 업데이트되어 더이상 지원하지 않는 이전 버전의 API를 요청한 경우
NO_AUTHENTICATION_FOUND	401 Unauthorized	요청 내 인증 정보가 존재하나, 정보의 불일치 또는 존재하지 않는 계정 정보 에러 [Example Cases] path 또는 header에 인증 정보가 포함되었으나 유효기간이 지난 경우 path 또는 header에 인증 정보가 포함되었으나 다른 계정의 인증 정보를 사용한 경우
AUTHENTICATION_FAILED	401 Unauthorized	요청 내 인증 정보 포함되지 않는 경우에 대한 에러 [Example Cases] path 혹은 header에 인증 정보를 입력하지 않은 경우
PERMISSION_DENIED	403 Forbidden	인증은 완료되었으나 인가되지 않은 리소스에 접근하는 경우 권한 에러 [Example Cases] 인증 정보의 권한이 없는 요청을 진행한 경우
WRONG_ENDPOINT	404 Not Found	요청한 API 경로가 존재하지 않는 경우 [Example Cases] 잘못된 API 경로를 요청한 경우 존재하지 않는 API 버전을 요청한 경우 서버에서 제거되었거나 변경된 API를 호출한 경우
NOT_SUPPORTED_CHAIN	404 Not Found	요청한 체인에서 지원하지 않는 서비스 경로를 요청한 경우 [Example Cases] 해당 path의 기능에서 path parameter의 {protocol}필드에 지정된 체인을 서비스하지 않는 경우
RESOURCE_NOT_FOUND	404 Not Found	요청한 리소스가 서버에 존재하지 않는 경우 [Example Cases] 서버에 없는 데이터를 요청한 경우 존재하지 않는 파일이나 리소스에 대한 요청 유효하지 않은 ID나 키를 사용하여 데이터를 요청한 경우
METHOD_NOT_ALLOWED	405 Method Not Allowed	허용되지 않는 HTTP 메서드로 요청한 경우 [Example Cases] 유효한 HTTP 메서드 타입이지만 요청한 API에서는 지원하지 않는 경우 유효하지 않은 HTTP 메서드 타입으로 요청한 경우
TIMEOUT	408 Request Timeout	호출이 정해진 시간 이내에 완료되지 않는 경우 혹은 WAS 컨트롤러에서 목표로 한 시간 제한을 초과한 경우 [Example Cases] Transaction receipt 조회를 위한 체인에 대한 RPC 호출이 5초 이내에 완료되지 않은 경우, 재시도 3회 포함 모두 실패 시 클라이언트에게 최종 TIMEOUT 에러 반환함. Elasticsearch 서비스 호출시, receipt 조회 응답이 5초 내에 완료되지 않은 경우
RESOURCE_ALREADY_EXISTS	409 Conflict	이미 존재하는 리소스에 대한 중복 생성 요청한 경우 [Example Cases] 중복 생성될 수 없는 리소스에 대한 중복 생성 시도 요청된 식별 값을 키 값으로 생성 요청시, 해당 식별 값이 이미 존재하는 경우
REJECTED	409 Conflict	요청 처리가 서버로부터 거절된 경우
CONTENTS_TOO_LARGE	413 Payload Too Large	서버에서 설정된 payload 최대값을 초과한 경우
TOO_LONG_URI	414 URI Too Long	클라이언트 요청이 서버에서 해석가능한 최대 URI 길이를 초과한 경우 반환되는 에러.
TOO_MANY_REQUESTS	429 Too Many Request	허용된 Rate limit을 초과하는 경우 [Example Cases] 초당/분당 Compute Unit 제한이 있는 경우 초당/분당 Bytes 사이즈 제한이 있는 경우 초당/분당 Requests 제한이 있는 경우
EXCEEDED_QUOTA_LIMIT	429 Too many request	허용된 Quota limit을 초과한 경우 [Example Cases] 사용자의 요금제에서 제공하는 월별 사용량을 초과한 경우
INTERNAL_SERVER_ERROR	500 Internal Server Error	내부 서버 오류 [Example Cases] 처리되지 않는 런타임 에러가 발생하는 경우 인프라(DB, 스토리지, 큐, 캐시 등) 및 외부 서비스 호출과 같은 도메인 컨텍스트 이외의 영역에서 발생하는 모든 내부 에러의 경우
INTERRUPTED	500 Internal Server Error	다중 요청을 처리하는 과정에서 특정 클라이언트의 요청에 대해 일시적으로 처리가 실패한 경우. 서버 부하로 인한 에러로 판단 할 수 있음.
UNAVAILABLE	503 Service Unavailable	서버의 서비스 제공이 불가능한 상태. 인프라의 다운 또는 서비스 중단을 동반한 업그레이드 작업 등으로 인해 반환될 수 있는 에러.