요청 오류
Error 400
표400 오류 코드| 구분 | 설명 |
|---|---|
| 현상 | _code: 400 |
| 원인 | 해당 오류는 API 요청 시 파라미터 정보가 유효하지 않을 때 발생합니다. |
| 해결책 | API 요청 파라미터가 유효한지 확인합니다. |
Error 401
표401 오류 코드| 구분 | 설명 |
|---|---|
| 현상 | _code: 401, Unauthorized |
| 원인 | 해당 오류는 주로 인증 토큰이 만료되었을 때 표시됩니다. |
| 해결책 | 다음과 같이 인증 토큰을 다시 발급하시기 바랍니다. 1. [Kakao Developers] 토큰 갱신하기의 절차대로 Access Token을 갱신합니다. 2. 만약 언급한 절차 수행 중 계속 에러가 발생한 경우에는 Refresh Token도 만료된 상황입니다. - 따라서 Connect Web 가입 절차를 다시 수행하시기 바랍니다. |
Error 481
표481 오류 코드| 구분 | 설명 |
|---|---|
| 현상 | _code: 481, Upgrade Required |
| 원인 | 해당 오류는 KakaoI-Agent의 애플리케이션 버전을 업그레이드가 필요할 경우에 표시됩니다. - 카카오 i 서버에서 임의로 정하는 값은 아닙니다. - 고객사와 협의된 애플리케이션 버전을 기준으로 해당 오류가 발생할 수 있습니다. |
| 해결책 | 애플리케이션 또는 SDK 버전을 최신 버전으로 업데이트해야 합니다. |
Error 482
표482 오류 코드| 구분 | 설명 |
|---|---|
| 현상 | _code: 482, Approvals Changed |
| 원인 | 해당 오류는 미승인 약관에 대한 동의가 필요한 경우에 표시됩니다. - 서비스 가입 이후, 해당 서비스 이용 중에 필수 약관이 추가되는 경우도 발생합니다. |
| 해결책 | 추가된 미승인 약관에 동의하기 위해 Connect Web 가입 절차를 다시 수행하시기 바랍니다. |
Error 483
표483 오류 코드| 구분 | 설명 |
|---|---|
| 현상 | _code: 483, Not a Registered User |
| 원인 | 해당 오류는 미등록 사용자일 때 표시됩니다. - 해당 사용자가 헤이카카오 서비스에 가입되지 않은 경우에 발생합니다. - 탈퇴된 사용자의 인증 정보가 사용된 경우 발생합니다. |
| 해결책 | 고객사에서는 카카오 i 서비스 탈퇴에 대한 사용자 정보 삭제 등과 같은 작업들을 디케이테크인 담당자와 논의하여 탈퇴 관련 Callback 기능을 받을 수 있습니다. 또는 고객사에서 사용자 정보 등을 따로 관리하는 경우에는 디케이테크인 담당자와 논의하여 해당 483 에러 코드를 받지 않을 수도 있습니다. |
| <개발 단계> 1. 인증 헤더를 구성하는 사용자 정보가 토큰 발급의 응답으로 구성되었는지 확인합니다. - app_user_id: "KakaoI-User: AU {app_user_id}"- access_token: "Authrorization: Bearer {access_token}""2. 위의 정보가 확인되지 않을 경우, 탈퇴된 사용자이므로 Connect Web 가입 절차를 수행하시기 바랍니다. |
|
| <운영 단계> Connect Web 가입 절차를 수행하시기 바랍니다. |
Error 485
표485 오류 코드| 구분 | 설명 |
|---|---|
| 현상 | _code: 485, Not a Registered UserApplication |
| 원인 | 해당 오류는 애플리케이션이 미등록된 경우에 표시됩니다. - KakaoI-Agent를 구성하는 AIID가 유효하지 않은 경우에 발생할 수 있습니다. - 카카오 i 서비스에서 AIID가 삭제된 경우에 발생할 수 있습니다. - AIID는 90일 이상 미사용 또는 사용자가 회원 탈퇴 시 자동 삭제됩니다. |
| 해결책 | 다음과 같이 AIID 발급을 다시 진행합니다. |
| <개발 단계> 1. AIID 발급 절차에 따라 발급받은 AIID가 KakaoI-Agent 헤더에 제대로 설정되어 있는지 확인합니다. KakaoI-Agent: KVS/{버전} ({OS}; {플랫폼}; {제품정보}; AIID ${AIID}) {앱패키지}/{버전문자}/{버전코드} SDK/{버전}2. KakaoI-Agent 헤더 값이 정상으로 확인되지 않은 경우에 디케이테크인 담당자에게 확인을 요청합니다. |
|
| <운영 단계> AIID 발급을 다시 수행하여 KakaoI-Agent의 AIID를 교체합니다. |
서버 오류
Error 500
표500 오류 코드| 구분 | 설명 |
|---|---|
| 현상 | _code: 500 |
| 원인 | 해당 오류는 카카오 i 서버 내부 오류가 발생했을 때 표시됩니다. |
| 해결책 | 오류가 복구될 때까지 대기합니다. - 해당 오류가 지속될 경우, 디케이테크인 담당자에게 문의 부탁드립니다. |
Error 503
표503 오류 코드| 구분 | 설명 |
|---|---|
| 현상 | _code: 503, Service Unavailable |
| 원인 | 해당 오류는 카카오 i 서비스가 점검 중일 때 표시됩니다. |
| 해결책 | 서비스 점검이 종료될 때까지 잠시 기다려주시기 바랍니다. - 해당 오류가 지속될 경우, 디케이테크인 담당자에게 문의 부탁드립니다. |
음성 인식 오류
표음성 인식 관련 오류| 오류 코드 | 오류 메시지 | 장애 여부 | 현상 및 해결방안 |
|---|---|---|---|
| 0 | ERROR_NONE | - | 오류 아님 |
| 1 | ERROR_AUDIO | - | 오디오 녹음 관련 오류 |
| 2 | ERROR_NETWORK | 장애 |
네트워크 관련 오류 - 서비스 장애로 담당자에게 문의 필요 |
| 3 | ERROR_NETWORK_TIMEOUT | 장애 |
네트워크 타임아웃 - 간혹적으로 발생할 수 있으나, 지속적될 경우에는 담당자에게 문의 필요 |
| 4 | ERROR_NO_RESULT | - | 결과 없음 |
| 5 | ERROR_CLIENT_INETRNAL | 장애 |
클라이언트 내부 오류 - 서비스 장애로 담당자에게 문의 필요 |
| 6 | ERROR_SERVER_INTERNAL | 장애 |
서버 내부 오류 - 서비스 장애로 담당자에게 문의 필요 |
| 7 | ERROR_SERVER_TIMEOUT | - | 서버 타임아웃 - 사용자가 데이터를 Read Timeout동안 데이터를 보내지 않으면 발생 - 이어말하기(장문 음성 인식) 요청이 1시간을 초과할 경우 발생 |
| 8 | ERROR_SERVER_AUTHENTICATION | - | 인증 실패 |
| 11 | ERROR_SERVER_UNSUPPORT_SERVICE | - | 음성 서버에서 지원하지 않는 서비스 코드 - 클라이언트가 잘못된 서비스 모드를 전송하여 발생 - X-DSS-Service 헤더에 알맞은 값을 셋팅하여 전송 |
| 12 | ERROR_SERVER_USERDICT_EMPTY | - | 사용자 사전이 꼭 필요한 서비스에서 사용자 사전이 비어있는 경우 발생 |
| 13 | ERROR_SERVER_ALLOWED_REQUESTS_EXCESS | - | 음성 서비스 최대 허용 횟수 초과 - 서비스 서버 개수 증가 문의 필요 |
| 15 | ERROR_AUDIO_DATA_WAIT_TIMEOUT | - | 오디오 데이터 대기 시간 초과 오류 |
| 16 | ERROR_SERVER_WAKEUP_NO_RESULT | - | 서버용 Wake-up 인식 결과 없음 - (오류 아님) 외부 소음에 의해 기기 Wake-up 오작동일 수 있음 - 정확한 Wake-up 발화로 재시도 |
| 17 | ERROR_SERVER_OBSOLETE_SERVICE | - | 더 이상 서비스하지 않음 |
| 18 | ERROR_LEPD_RESULT_TIMEOUT | - | 이어말하기에서 일정 시간 정상 응답이 없을 때 발생하는 타임아웃 - 사용자가 일정 시간 이상으로 침묵할 때 주로 발생 - 기준 시간 연장 요청 가능 |
관련 문서
AI Service Agent Kakao i Agent Service Agent 등록 Kakao i Agent Service Agent Interface Kakao i Agent 구현 시나리오 Kakao i Agent Troubleshooting Kakao i Agent