본문으로 건너뛰기

10 - 오류 반환

본 장에서는 CodeVASP 솔루션의 모든 API에서 공통으로 사용되는 오류 응답에 대해 설명합니다. 코드 내 모든 API는 요청 처리 중 오류가 발생할 때 아래 설명된 Status Code, Error Type, 그리고 ErrorMsg를 결합한 오류 응답을 반환하도록 설계되었습니다.

VASP 서버에 구현된 CodeVASP의 VASP API 역시 아래 분류에 따라 오류를 반환하도록 구현해 주십시오.

CodeVASP API 서버에서 반환하는 오류와 VASP API 서버에서 반환하는 오류는 상태 코드에 따라 다를 수 있습니다. 동일한 ErrorType이라도 상태 코드에 따라 오류를 반환하는 주체가 다릅니다.

📌'invalid'와 'denied' 'Search VASP by Wallet' 요청에 대한 invalid 결과나 'Asset Transfer Authorization' 요청에 대한 denied 결과는 요청이 성공적으로 처리되었음을 나타내므로 오류로 간주되지 않습니다.

422 Validation Error​

이 오류는 CodeVASP 서버에서 반환됩니다.

CodeVASP API 서버가 수신한 메시지의 매개변수 검증에 실패했을 때 CodeVASP API 서버에서 반환하는 오류입니다. 이는 CodeVASP API 서버에서 직접 처리되는 메시지와 VASP API로 전달되는 메시지 모두에 적용됩니다.

  • errorType: 오류 유형
    • INVALID_TARGET_VASP_ID: 매개변수로 입력된 VASP의 Entity ID가 유효하지 않습니다.
    • MISSING_REQUIRED_MSG_FIELD: 요청 처리 시 필수 메시지 필드가 누락되었습니다.
    • MISSING_HEADER_FIELD: 필수 헤더 필드가 누락되었습니다.
    • INVALID_MSG_FIELD_VALUE: 메시지 필드의 값이 유효하지 않습니다.
    • DUPLICATED_HEADER_NONCE: 메시지 헤더의 Nonce 값이 1분 내에 재전송된 경우입니다. 요청을 보낼 때마다 변경되는 값으로 설정해 주십시오.
    • INVALID_HEADER_SIGNATURE: 메시지 헤더의 서명 검증이 실패한 경우입니다.
    • INVALID_RECEIVER_PUBLIC_KEY: 요청 헤더의 상대방 공개키가 유효하지 않은 경우입니다. 상대방 VASP의 공개키가 변경되었을 수 있습니다.
    • ILLEGAL_FORMAT_OF_ORIGIN: 헤더 origin의 문자열 형식이 비정상적입니다. {AllianceName}:{VaspEntityId} 형식으로 전송해 주십시오.
    • INVALID_ORIGIN: 헤더 origin의 값이 올바르지 않습니다. VaspEntityId를 찾을 수 없거나 AllianceName이 유효하지 않습니다.
    • INVALID_BENEFICIARY: 수신자 VASP가 유효하지 않습니다. API가 수신자 VASP를 필요로 하지만 제공된 VASP가 유효하지 않거나 찾을 수 없을 때 발생합니다.
  • errorMsg: ErrorType에 대한 상세 정보를 전달하기 위해 사용됩니다. 이는 선택사항입니다.
{
  "errorType": "INVALID_TARGET_VASP_ID",
  "errorMsg": "VaspEntityId received is."
}

408 Request Timeout​

이 오류는 CodeVASP API 서버에서 반환됩니다.

CodeVASP API 서버가 실제로 요청을 처리하는 VASP API 서버에 요청을 전달했을 때 응답 시간이 초과된 경우 CodeVASP API 서버에서 반환하는 오류입니다.

  • errorType: 오류 유형
    • BENEFICIARY_VASP_REQUEST_TIMEOUT
  • errorMsg: ErrorType에 대한 상세 정보를 전달하기 위해 사용됩니다. 이는 선택사항입니다.
{
  "errorType": "BENEFICIARY_VASP_REQUEST_TIMEOUT",
  "errorMsg": "Beneficiary VASP does not respond."
}

429 Too Many Requests​

이 오류는 CodeVASP API 서버에서 반환됩니다. 전체 시스템 성능에 영향을 줄 수 있는 특정 API들은 소스 IP당 초당 전송할 수 있는 요청 수를 제한합니다. 요청 수가 제한값을 초과하면 이 오류를 반환합니다.

  • errorType: 오류 유형
    • TOO_MANY_REQUESTS
  • errorMsg: ErrorType에 대한 상세 정보를 전달하기 위해 사용됩니다. 이는 선택사항입니다.
{
  "errorType": "TOO_MANY_REQUESTS",
  "errorMsg": "The request has exceeded the limit (40) per minute, source IP."
}

500 Internal Server Error​

이 오류는 CodeVASP API 서버에서 반환됩니다.

CodeVASP API가 요청을 직접 처리하는 중 오류가 발생했을 때 이런 종류의 오류를 반환합니다.

  • errorType: 오류 유형
    • RECEIVED_WRONG_JSON_MESSAGE: 수신자가 응답한 JSON 메시지를 읽을 수 없습니다.
    • RECEIVED_MSG_MISSING_FIELD: 수신자가 응답한 메시지에 누락된 필드가 있습니다.
    • CODE_SERVER_INTERNAL_ERROR: CodeVASP 서버가 요청을 처리하는 중 오류가 발생했습니다.
  • errorMsg: ErrorType에 대한 상세 정보를 전달하기 위해 사용됩니다. 이는 선택사항입니다.
{
  "errorType": "CODE_SERVER_INTERNAL_ERROR",
  "errorMsg": "An internal error occurs while processing."
}

503 Service Unavailable​

이 오류는 예상치 못한 상황에서만 VASP(귀하의) API 서버에서 반환됩니다. 정상적인 경우에는 200으로 응답해야 합니다.

VASP API 서버가 요청을 처리하는 중 오류가 발생한 경우 VASP에서 반환하는 오류입니다. VASP API 서버가 오류를 반환하면, 이는 CodeVASP API 서버를 통해 전달되어 요청을 보낸 VASP에게 전송됩니다.

Status Code와 ErrorType 분류는 CodeVASP API 서버와 완전히 일치하지 않습니다.

  • errorType: 오류 유형
    • UNKNOWN_TRANSFER_ID: 요청된 TransferId가 존재하지 않습니다.
    • VASP_BACKEND_INTERNAL_ERROR: VASP 백엔드가 요청을 처리하는 중 내부 오류가 발생했습니다.
    • MISSING_REQUIRED_MSG_FIELD: 필수 메시지 필드가 누락되었습니다.
    • MISSING_HEADER_FIELD: 필수 헤더 필드가 누락되었습니다.
    • INVALID_MSG_FIELD_VALUE: 메시지 필드의 값이 유효하지 않습니다.
    • DUPLICATED_TRANSFER_ID: 수신된 TransferId가 이미 존재하는 경우입니다.
    • INVALID_HEADER_SIGNATURE: 메시지 헤더의 서명 검증이 실패한 경우입니다.
    • INVALID_ENCRYPTED_BODY: 암호화된 메시지를 복호화할 수 없는 경우입니다.
    • UNACCEPTABLE_REQUEST: 처리할 수 없는 요청입니다. 요청의 내용을 이를 수신한 VASP에서 처리할 수 없습니다.
  • errorMsg: ErrorType에 대한 상세 정보를 전달하기 위해 사용됩니다. 이는 선택사항입니다.
{
  "errorType": "VASP_BACKEND_INTERNAL_ERROR",
  "errorMsg": "An VASP backend server failed to process request."
}