오류 처리
Context API 오류의 원인과 처리 방법, 기본 동작과 재시도의 구현 기준을 설명합니다.
Context API 호출에 실패했을 때는 기존 화면이나 기본 메시지를 제공하는 기본 동작이 필요합니다. 정상 응답, API 오류와 시간 초과를 구분해 처리하고 오류 내용을 기록하면 원인을 확인할 수 있습니다.
오류 응답 읽기
Context API의 오류 응답 본문에는 requestId와 error가 포함됩니다. 아래는 식별자 연결이나 예측 데이터를 찾지 못한 경우의 HTTP 404 응답 예시입니다.
{
"requestId": "01915c8e-7a12-7d3f-8b2a-1f2e3d4c5b6a",
"error": {
"code": "CONTEXT_DATA_NOT_FOUND",
"message": "Context identifier or features were not found.",
"retryable": false
}
}오류 응답의 각 필드는 다음과 같이 활용할 수 있습니다.
| 필드 | 처리 방법 |
|---|---|
requestId | 오류 로그와 문의 내용에 포함하면 해당 요청을 찾을 수 있습니다. |
error.code | 프로그램에서 오류 원인을 구분하는 기준입니다. |
error.message | 오류 원인을 설명하는 문구입니다. 문구를 비교해 프로그램의 동작을 결정하지 않아야 합니다. |
error.retryable | true이면 재시도 여부를 판단해 주세요. 재시도할 때는 요청 간격을 늘리고, 횟수와 전체 대기 시간을 제한해야 합니다. false이면 원인을 해결한 뒤 다시 요청해야 합니다. |
오류 코드별 원인과 처리 방법
Context API의 HTTP 상태 코드와 오류 코드에 따른 원인과 처리 방법은 다음과 같습니다.
| HTTP 상태 코드 | 오류 코드 | 원인과 처리 방법 |
|---|---|---|
400 | INVALID_JSON | JSON을 해석할 수 없습니다. 요청 본문의 JSON 문법을 수정해 주세요. |
401 | UNAUTHORIZED | 인증 정보가 없거나 유효하지 않습니다. Bearer 형식과 대상 앱의 SDK 토큰을 확인해 주세요. |
404 | CONTEXT_DATA_NOT_FOUND | 식별자 연결이나 예측에 필요한 앱 사용자 데이터가 없습니다. 토큰에 해당하는 앱과 사용자 ID를 확인하고, 에어브릿지 담당자에게 연결 정보와 데이터 준비 상태를 문의해 주세요. |
409 | CONTEXT_INACTIVE | Context 설정이나 활성 모델이 없습니다. 대상 앱의 CUE 사용 설정을 확인해 주세요. |
409 | IDENTIFIER_CONFLICT | 사용자 식별자의 연결 정보가 충돌했습니다. 에어브릿지 담당자에게 식별자 연결 상태를 문의해 주세요. |
413 | PAYLOAD_TOO_LARGE | 요청 본문이 65,536바이트를 초과했습니다. 본문 크기를 줄여 주세요. |
422 | VALIDATION_ERROR | 요청 형식이 규격과 다릅니다. Content-Type이 JSON인지, 비어 있지 않은 ID를 정확히 1개 보냈는지 확인해 주세요. 정의되지 않은 필드는 제거해야 합니다. |
500 | CONTEXT_FEATURE_INVALID | 저장된 모델 입력 데이터가 유효하지 않습니다. 자동으로 재시도하지 말고 requestId와 함께 문의해 주세요. |
503 | AUTHENTICATION_UNAVAILABLE | 인증 정보를 일시적으로 조회할 수 없습니다. error.retryable을 확인하고 재시도할 수 있으면 간격을 두고 재시도해 주세요. |
503 | AUTHENTICATION_STATE_INVALID | 서버의 인증 설정에 문제가 있습니다. 반복해서 호출하지 말고 에어브릿지 담당자에게 문의해 주세요. |
503 | CONTEXT_UNAVAILABLE | 데이터 조회나 모델 실행에 실패했거나 모델 설정을 확인해야 합니다. error.retryable에 따라 재시도하거나 문의해 주세요. |
503 | CONTEXT_LOG_UNAVAILABLE | 요청 로그를 기록하지 못했습니다. error.retryable을 확인해 재시도 여부를 판단해 주세요. 재시도할 때는 요청 간격을 늘리고, 횟수와 전체 대기 시간을 제한해야 합니다. |
같은 HTTP 503이라도 오류 코드와 원인에 따라 재시도 여부가 다릅니다. 재시도 여부는 HTTP 상태 코드와 함께 error.code와 error.retryable을 기준으로 판단해야 합니다.
기본 동작과 재시도 구현하기
기본 동작과 재시도를 구현하면 API 호출에 실패해도 앱 사용자가 서비스를 계속 사용할 수 있습니다.
- 오류나 시간 초과가 발생하거나 응답을 읽을 수 없으면 기존 화면이나 기본 메시지를 제공해야 합니다.
- 오류 응답을 읽을 수 있으면
error.code와error.retryable을 확인해 주세요. error.retryable이true이면 재시도 여부를 판단해 주세요. 재시도할 때는 요청 간격을 늘리고 최대 횟수와 전체 대기 시간을 제한해야 합니다. 서비스에서 허용할 수 있는 대기 시간에 맞춰 정책을 정해 주세요.error.retryable이false이면 요청, 설정 또는 데이터에서 원인을 찾아 해결한 뒤 다시 요청해야 합니다.
시간 초과나 네트워크 오류가 발생하면 서버가 반환한 error.retryable을 읽지 못할 수 있습니다. 이때도 기본 화면이나 메시지를 먼저 제공해야 합니다. 재시도 여부는 서비스의 정책에 따라 정할 수 있으며, 재시도한다면 요청 간격을 늘리고 횟수와 전체 대기 시간을 제한해야 합니다.
404 CONTEXT_DATA_NOT_FOUND는 앱 사용자 정보를 얻지 못한 상태를 뜻합니다. 구매 확률이 0이거나 등급이 low인 응답과는 다릅니다.
요청 경로와 메서드 확인하기
Context API를 호출할 때는 정해진 URL과 POST 메서드를 사용해야 합니다. 잘못된 URL이나 POST 이외의 메서드를 사용하면 아래와 같은 일반 404 응답이 반환될 수 있습니다. Context API의 오류 객체와 형태가 다르므로 클라이언트에서 별도로 처리해야 합니다.
{
"error": "not found"
}요청 URL과 메서드는 Context API의 Endpoint에서 확인할 수 있습니다. HTML처럼 JSON이 아닌 오류 응답을 받았을 때도 기본 동작을 실행해야 합니다.
연동 테스트와 문의
서비스에 적용하기 전에 정상 응답, 인증 오류, 데이터가 없는 경우와 시간 초과를 각각 테스트해야 합니다. 각 상황에서 의도한 화면이나 메시지가 제공되는지도 확인해야 합니다. 테스트 사용자와 응답 예시를 활용하면 운영 중인 데이터를 바꾸지 않고 확인할 수 있습니다.
에어브릿지 담당자에게 문의할 때는 호출 시각과 시간대, requestId, HTTP 상태 코드와 error.code를 알려 주세요. requestId를 받지 못했다면 호출 URL, 메서드와 오류가 발생한 상황을 함께 알려 주세요.