# 오류 처리

Context API 오류의 원인과 처리 방법, 기본 동작과 재시도의 구현 기준을 설명합니다.

Source: https://cue.airbridge.io/docs/ko/reference/errors
Language: ko
Updated: 2026-10-15

Context API 호출에 실패했을 때는 기존 화면이나 기본 메시지를 제공하는 기본 동작이 필요합니다. 정상 응답, API 오류와 시간 초과를 구분해 처리하고 오류 내용을 기록하면 원인을 확인할 수 있습니다.

## 오류 응답 읽기

Context API의 오류 응답 본문에는 `requestId`와 `error`가 포함됩니다. 아래는 식별자 연결이나 예측 데이터를 찾지 못한 경우의 HTTP `404` 응답 예시입니다.

```json
{
  "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 호출에 실패해도 앱 사용자가 서비스를 계속 사용할 수 있습니다.

1. 오류나 시간 초과가 발생하거나 응답을 읽을 수 없으면 기존 화면이나 기본 메시지를 제공해야 합니다.
2. 오류 응답을 읽을 수 있으면 `error.code`와 `error.retryable`을 확인해 주세요.
3. `error.retryable`이 `true`이면 재시도 여부를 판단해 주세요. 재시도할 때는 요청 간격을 늘리고 최대 횟수와 전체 대기 시간을 제한해야 합니다. 서비스에서 허용할 수 있는 대기 시간에 맞춰 정책을 정해 주세요.
4. `error.retryable`이 `false`이면 요청, 설정 또는 데이터에서 원인을 찾아 해결한 뒤 다시 요청해야 합니다.

시간 초과나 네트워크 오류가 발생하면 서버가 반환한 `error.retryable`을 읽지 못할 수 있습니다. 이때도 기본 화면이나 메시지를 먼저 제공해야 합니다. 재시도 여부는 서비스의 정책에 따라 정할 수 있으며, 재시도한다면 요청 간격을 늘리고 횟수와 전체 대기 시간을 제한해야 합니다.

`404 CONTEXT_DATA_NOT_FOUND`는 앱 사용자 정보를 얻지 못한 상태를 뜻합니다. 구매 확률이 `0`이거나 등급이 `low`인 응답과는 다릅니다.

## 요청 경로와 메서드 확인하기

Context API를 호출할 때는 정해진 URL과 `POST` 메서드를 사용해야 합니다. 잘못된 URL이나 `POST` 이외의 메서드를 사용하면 아래와 같은 일반 `404` 응답이 반환될 수 있습니다. Context API의 오류 객체와 형태가 다르므로 클라이언트에서 별도로 처리해야 합니다.

```json
{
  "error": "not found"
}
```

요청 URL과 메서드는 [Context API의 Endpoint](/docs/ko/reference/context-api#endpoint)에서 확인할 수 있습니다. HTML처럼 JSON이 아닌 오류 응답을 받았을 때도 기본 동작을 실행해야 합니다.

## 연동 테스트와 문의

서비스에 적용하기 전에 정상 응답, 인증 오류, 데이터가 없는 경우와 시간 초과를 각각 테스트해야 합니다. 각 상황에서 의도한 화면이나 메시지가 제공되는지도 확인해야 합니다. 테스트 사용자와 응답 예시를 활용하면 운영 중인 데이터를 바꾸지 않고 확인할 수 있습니다.

에어브릿지 담당자에게 문의할 때는 호출 시각과 시간대, `requestId`, HTTP 상태 코드와 `error.code`를 알려 주세요. `requestId`를 받지 못했다면 호출 URL, 메서드와 오류가 발생한 상황을 함께 알려 주세요.