API를 호출하면 HTTP Status Code로 API 처리 결과를 받고 HTTP Response Body로 응답 값을 받습니다. 응답 값은 OpenAPI에 따라 XML또는 JSON형식이 될 수 있습니다. 따라서 API 응답 처리를 할 때, 먼저 HTTP Status Code를 통해 정상 처리 여부를 확인하여 응답 형식에 따라 결과를 파싱하여 서비스에 이용할 수 있습니다.
| HTTP 상태 코드 | 에러 원인 상세 | 조치 방안 |
|---|---|---|
| 401(인증실패) | 애플리케이션 클라이언트 아이디와 시크릿 값이 없거나 잘못되었을 경우 | 애플리케이션을 등록하고, 내 애플리케이션 메뉴 클라이언트 아이디와 시크릿값을 확인합니다. |
| 401(인증실패) | 클라이언트 아이디와 시크릿 값을 HTTP 헤더에 정확히 설정하지 않고 호출했을 경우 | 클라이언트 아이디와 시크릿 값은 URL이나 폼이 아니라 지정된 이름의 HTTP 헤더로 전송해야 합니다. |
| 401(인증실패) | API 권한 설정이 안되어 있을 경우 | 내 애플리케이션 메뉴의 ‘API 설정’ 탭에서 그 API가 추가되어 있는지 확인합니다. |
| 401(인증실패) | 로그인 오픈 API를 호출할 때 접근 토큰(access_token) 값이 빠졌거나 잘못된 값(만료)을 설정하였을 경우 | 접근 토큰 값을 헤더에 정확히 세팅했는지, 값이 유효한지 확인합니다. |
| 403(서버가 허용하지 않는 호출) | https가 아닌 http로 호출하였을 경우 | API 요청 URL이 https인지 확인합니다. |
| 404(API 없음) | API 요청 URL이 잘못되었을 경우 | API 요청 URL에 오타가 없는지 확인합니다. |
| 405(메서드 허용 안함) | HTTP 메서드를 잘못하여 호출하였을 경우 (POST인데 GET으로 호출) | API 명세에서 지원하는 HTTP 메서드를 확인합니다. |
| 400(요청 변수 확인), 403(호출 금지), 500(서버 오류) | 필수 요청 변수가 빠졌거나 요청변수 이름이 잘못되었을 경우 | API 명세에서 필수 요청 변수 목록을 확인합니다. |
| 400(요청 변수 확인), 403(호출 금지), 500(서버 오류) | 요청 변수 값을 URL 인코딩하지 않고 전송하였을 경우 | API 명세에서 그 요청 변수가 URL 인코딩이 필요한지 확인합니다. |
| 429(호출 한도 초과 오류) | 오픈 API를 호출할 때 일 허용량을 초과하였을 경우 | 일 허용량 초과시 제휴신청을 합니다. |
| 500(서버오류) | API 호출은 정상적으로 했지만, API 서버 유지보수나 시스템 오류로 인한 에러가 발생하였을 경우 | 포럼에 오류를 신고 합니다. |
에러 메세지의 포맷은 에러가 발생하는 위치와 관계없이 동일합니다.
에러의 성격에 따라 HTTP 응답 코드는 400번대 혹은 500번대 에러 코드로 리턴됩니다.
에러 메세지는 XML 또는 JSON 포맷으로 제공되며 에러의 내용을 담고 있는 errorMessage와 에러 코드를 담는 errorCode 두 요소로 구성됩니다. API 이름에 translate.xml처럼 확장자로 xml이 붙는 API들만 XML 형태의 에러 메세지를 발생하고, 그 외에는 JSON 형태의 에러 메세지를 발생합니다. 아래는 XML과 JSON 형태의 에러 메세지 예입니다.
<?xml version="1.0" encoding="UTF-8"?>
<result>
<errorMessage><![CDATA[Authentication failed (인증 실패하였습니다.)]]></errorMessage>
<errorCode><![CDATA[024]]></errorCode>
</result>
{
"errorMessage": "Authentication failed (인증에 실패하였습니다.)",
"errorCode": "024"
}