본문으로 건너뛰기

업스트림 응답 상태

현재 스페이스에서 관찰된 모델의 오류와 지연 조회

모델 목록과 별도로 장애, 지연과 상태 확인 불가 항목을 조회하고 상태 값, 유효기간 및 조회 실패를 구분합니다.

페이지 목차

조회 범위와 요청 조건

GET
https://gw.letsur.ai/v1/models/upstream-health-check
인증Authorization: Bearer <API_KEY>

API 키에 연결된 스페이스에서 이용할 수 있는 에셋의 업스트림 응답 상태를 조회합니다. 상태는 모델 호출에서 관찰된 장애와 지연을 반영하지만, 개별 호출의 성공이나 실패까지 확정하지는 않습니다.

항목응답
모델 호출에서 장애나 지연이 관찰된 항목포함합니다
최신 상태를 확인할 수 없는 항목포함합니다
정상(operational) 항목제외합니다
다른 스페이스의 에셋제외합니다
현재 스페이스에서 이용할 수 없는 에셋제외합니다
  • 조회할 스페이스의 AI 게이트웨이 API 키

    조회할 스페이스는 API 키로 결정됩니다. 콘솔에서 선택한 스페이스는 이 요청에 전달되지 않습니다. 키는 Gateway 인증과 기본 URL에 따라 준비하고, 관리 API 키는 사용하지 않습니다.

  • 본문과 query 파라미터 없는 요청

    요청 본문과 query 파라미터는 없습니다. 이 API는 space_id를 포함한 모든 query 파라미터를 거절합니다.

이 상태 목록은 Models가 반환하는 목록(모델 코드와 단가)과 다릅니다. /v1/models 응답에는 status 필드가 없으니 모델별 상태는 상태 조회 응답의 model_code로 확인합니다. 두 API의 목록 범위가 같다고 가정하지 않습니다.

콘솔에서 상태를 확인하려면 공급사 헬스체크 안내를 참고하세요.

상태 조회 예시

조회할 스페이스의 AI 게이트웨이 API 키로 직접 HTTP 요청을 보냅니다. 아래 cURL과 Python 예제는 서버 환경 변수 LETSUR_API_KEY를 읽습니다. 이 요청은 저장된 판정 결과를 읽을 뿐 새 모델 호출을 실행하지 않습니다.

Python 예제는 Python 3에서 실행합니다. 예제는 요청을 자동으로 재시도하지 않습니다. 오류 응답이 포함된 출력은 공개 로그에 남기지 마세요.

cURL
curl "https://gw.letsur.ai/v1/models/upstream-health-check" \ -H "Authorization: Bearer $LETSUR_API_KEY"

응답 필드

조회에 성공하면 HTTP 200이 반환됩니다. 일부 또는 전체 항목의 status가 null이어도 HTTP 상태는 200입니다.

필드설명
items조회한 스페이스의 장애, 지연 또는 상태 확인 불가 항목입니다. 정상으로 판정된 항목은 제외되며, 반환할 항목이 없으면 빈 배열입니다.
items[].model_code모델 코드입니다. /v1/models의 id와 대조할 때 이 값을 씁니다.
items[].status현재 상태 객체입니다. 현재 상태를 확인할 수 없으면 null입니다.
items[].status.indicator아래의 장애 또는 지연 상태 중 하나입니다.
items[].status.since마지막으로 확정된 상태 변경 시각입니다. UTC ISO 8601 형식이며 Z로 끝납니다. 최초 판정이거나 변경 시각을 알 수 없으면 null입니다. 최근 조회 시각이 아닙니다.

다음은 응답 구조를 보여 주는 예시입니다. 실제 상태를 나타내지는 않습니다.

{ "items": [ { "model_code": "example-model-a", "status": { "indicator": "degraded", "since": "2026-11-05T01:00:00Z" } }, { "model_code": "example-model-b", "status": { "indicator": "partial_outage", "since": null } }, { "model_code": "example-model-c", "status": null } ] }

상태 값 읽기

status.indicator의 값은 다음과 같습니다. status: null의 처리는 연동에서 결과 처리하기에서 확인합니다.

값뜻
major_outage업스트림 호출에서 높은 실패율이나 심한 지연이 감지되었습니다. 모든 요청이 실패한다는 뜻은 아닙니다.
partial_outage업스트림 호출의 일부 요청에서 실패, 시간 초과 또는 요청 제한이 감지되었습니다.
degraded업스트림의 응답이나 처리 대기 시간이 평소보다 길어졌습니다.

since: null인 장애 항목도 응답에 포함됩니다. 게이트웨이는 indicator만 보고 정상 항목을 제외하며, since 값은 제외 기준에 쓰지 않습니다.

상태 유효기간

게이트웨이는 상태를 판정한 시각이 현재 시각 기준 5분 이내일 때만 그 판정을 최신 상태로 인정합니다. 판정 후 정확히 5분이 지난 시점까지 인정합니다.

판정 시각최신 상태로 인정
현재 시각 기준 5분 이내인정합니다
없거나 미래인정하지 않습니다
판정 후 5분 초과인정하지 않습니다

판정 결과에 따라 에셋은 응답에 다음과 같이 나타납니다.

판정 상황응답
전체 상태 판정이 최신이고 그 에셋의 오류나 지연 기록이 없음정상으로 판정해 결과에서 제외합니다.
판정 정보를 읽지 못함그 에셋의 status가 null로 반환됩니다.
모든 에셋의 상태를 확인할 수 없음각 항목이 결과에 그대로 남습니다.

이 판정만으로 장애 원인이 공급사에 있다고 확정하지 않습니다. 공급사 계정이나 설정 문제로 생긴 거절도 판정에 포함될 수 있습니다.

연동에서 결과 처리하기

HTTP 응답의 성공 여부와 모델의 상태를 나누어 처리합니다.

조회 결과앱이나 점검 프로그램의 처리
200, 상태 객체 있음model_code와 상태를 함께 표시합니다. 상태만으로 개별 호출의 성공이나 실패를 확정하지 않습니다.
200, status: null확인 불가로 표시합니다. 정상이나 장애로 확정하지 않습니다. 인증 실패나 목록 조회 실패를 뜻하지 않습니다.
200, 빈 items반환할 장애, 지연 또는 확인 불가 항목이 없는 결과입니다. 전체 모델 목록으로 사용하거나 모든 모델의 호출이 성공했다는 뜻으로 해석하지 않습니다.
HTTP 오류조회 실패로 처리합니다. 인증에 실패했거나 접근이 거부됐다면 이전 결과를 현재 요청의 유효한 결과로 사용하지 않습니다. 일시적 오류라면 직전 조회 결과를 최신 결과와 구별하고, 아래 ‘오류와 복구’의 기준을 따릅니다.

/v1/models의 id와 상태 응답의 model_code를 대조할 때 목록의 순서나 개수가 같다고 가정하지 않습니다. 상태 응답에서 빠졌다는 이유만으로 앱의 모델 선택 목록에서 항목을 제거하지 않습니다.

오류와 복구

오류의미와 대응
HTTP 401API 키가 없거나 유효하지 않습니다. 대응: AI 게이트웨이 API 키와 인증 헤더를 확인합니다.
HTTP 403키에 유효한 스페이스가 없거나 접근 정책이 요청을 거절했습니다. 대응: 키의 스페이스와 접근 정책을 확인합니다.
HTTP 422요청에 query 파라미터가 있습니다. 대응: query를 제거합니다. 스페이스는 API 키로 결정됩니다.
MODEL_STATUS_UNAVAILABLE (500)허용 에셋 목록을 완전하게 확인하지 못했거나 응답 전체가 유효하지 않습니다. detail.error에 이 값이 반환됩니다. 대응: 빈 목록이나 정상 상태로 처리하지 않습니다. 간격을 두고 제한적으로 다시 조회합니다.