응답 코드 링크 복사
응답 코드는 요청에 대한 상태를 나타내는 HTTP 상태 코드(HTTP status code)와 에러에 대한 정보를 담은 에러 코드(Error code)로 나뉩니다. 요청 성공 시 HTTP 상태 코드 200과 함께 요청에 대한 응답 바디(response body)가 반환되고, 요청이 실패하였을 경우 code와 msg로 이루어진 에러 코드를 반환합니다.
HTTP 상태 코드 링크 복사
HTTP 상태 코드(HTTP status code)란 응답 메시지의 첫 번째 줄에 나타나는 세 자리 숫자의 코드로 요청에 대한 상태 정보(성공 또는 실패)를 나타냅니다. 상태 코드는 크게 5가지로 분류되며, 상태 코드의 첫 번째 숫자로 응답의 종류를 파악할 수 있습니다. 자세한 정보는 RFC 2616을 참고하세요.
다음은 API 요청에 대해 응답하는 상태 코드의 종류와 의미입니다.
표 1
HTTP 상태 코드
| Code | Status | Description |
|---|---|---|
| 200 OK | 성공 | 서버가 클라이언트의 요청을 성공적으로 수행 응답 바디는 API마다 형식이 다를 수 있으니 각 API의 상세 설명 참고 |
| 400 Bad Request | 실패 | 일반적인 오류 서버가 클라이언트 오류를 감지해 요청을 처리하지 못한 상태. 주로 API에 필요한 필수 파라미터와 관련됨 |
| 401 Unauthorized | 실패 | 인증 오류(주로 토큰 관련) 해당 리소스에 대한 인증 자격 증명이 유효하지 않아 요청에 실패한 상태 |
| 403 Forbidden | 실패 | 권한 오류 서버에 요청은 전달되었으나 권한 문제로 인하여 요청이 거절된 상태 |
| 429 Too Many Request | 실패 | 쿼터 초과 정해진 쿼터(사용량)나 초당 요청 한도를 초과한 상태 |
| 500 Internal Server Error | 실패 | 시스템 오류(서버 관련 오류를 총칭) 요청을 처리하는 과정에서 서버가 예상치 못한 상태에 놓인 상태. |
| 502 Bad Gateway | 실패 | 시스템 오류 서로 다른 프로토콜을 연결해 주는 게이트웨이(Gateway)가 잘못된 프로토콜을 연결하거나, 연결된 프로토콜에 문제가 있어 통신이 제대로 되지 않은 상태 |
| 503 Service Unavailable | 실패 | 서비스 점검 중 서버가 요청을 처리할 준비가 되지 않은 상태 |
에러 코드 링크 복사
다음은 API 제품별로 발생할 수 있는 에러 코드 정보입니다. 에러 발생 시 code 중 해당하는 항목을 찾아 원인을 파악할 수 있습니다.
표 1
공통 에러 코드
| Code | HTTP status code | Description |
|---|---|---|
| -1 | 400 | 서버 내부에서 처리 중에 에러가 발생한 경우 해결 방법: 재시도 |
| -2 | 400 | 필수 인자가 포함되지 않은 경우나 호출 인자 값의 데이터 타입이 적절하지 않거나 허용된 범위를 벗어난 경우 해결 방법: 요청 파라미터 확인 |
| -3 | 403 | 해당 API를 사용하기 위해 필요한 기능(간편 가입, 동의 항목, 서비스 설정 등)이 활성화되지 않은 경우 해결 방법: 카카오디벨로퍼스의 내 애플리케이션에서 필요한 기능을 선택한 후, [활성화 설정]에서 ON으로 설정한 후 재호출 |
| -4 | 403 | 계정이 제재된 경우나 해당 계정에 제재된 행동을 하는 경우 |
| -5 | 403 | 해당 API에 대한 요청 권한이 없는 경우 해결 방법: 검수 진행하여 권한 획득 후 재호출 |
| -7 | 400 | 서비스 점검 또는 내부 문제가 있는 경우 |
| -8 | 400 | 올바르지 않은 헤더로 요청한 경우 해결 방법: 요청 헤더 확인 |
| -9 | 400 | 서비스가 종료된 API를 호출한 경우 |
| -10 | 400 | 허용된 요청 회수가 초과한 경우 해결 방법: 허용된 쿼터 확인 후 쿼터 범위 내로 호출 조정, 쿼터 및 제한 참고 |
| -401 | 401 | 유효하지 않은 앱 키나 액세스 토큰으로 요청한 경우, 등록된 앱 정보와 호출된 앱 정보가 불일치하는 경우 해결 방법: 앱 키(App Key) 확인 또는 토큰 갱신, 개발자 사이트에 등록된 앱 정보 확인 |
| -602 | 400 | 이미지 업로드 시 최대 용량을 초과하였을 경우 |
| -603 | 400 | 이미지 업로드나 스크랩 요청과 같이 오래 걸리는 작업이 필요한 API에서 수행 시간이 오래 걸리는 경우 |
| -903 | 400 | 등록되지 않은 개발자의 앱 키나 등록되지 않은 개발자의 앱 키로 구성된 액세스 토큰으로 요청한 경우 |
| -911 | 400 | 지원하지 않는 포맷의 이미지를 업로드하는 경우 |
| -9798 | 503 | 서비스 점검 중 |