# 결과 없음 또는 API 오류 : 어떻게 구분할까요?

> 빈 결과, 부분 응답 및 ROOTE API 오류를 구분하세요. 좌표, 필터, 적용 범위 및 한도를 확인하여 올바른 메시지를 표시합니다.

Source: https://www.roote.ai/ko/guides/%EA%B2%B0%EA%B3%BC%EC%97%86%EC%9D%8C-api%EC%98%A4%EB%A5%98-%EA%B5%AC%EB%B6%84%EB%B0%A9%EB%B2%95/
Language: ko
Author: ROOTE

결과가 없는 API와 오류가 발생한 API는 서로 다른 처리가 필요합니다. 성공한 검색도 조회 범위 내에 장소를 반환하지 않을 수 있습니다. 반면 네트워크 오류, 한도 초과 또는 소스 비가용성은 검색으로 결론을 낼 수 없게 합니다.

ROOTE에서는 HTTP 응답과 업무 상태, 예상되는 컬렉션, 적용 범위를 확인하세요. 이 과정은 서비스 호출 실패 시 "화장실 없음" 또는 지연 초과 후 "정류장 없음"을 방지합니다.

## 응답의 세 가지 레벨 읽기

| 레벨 | 확인할 항목 | 가능한 결론 |
| --- | --- | --- |
| 전송 | 연결, 지연, HTTP 상태 | 요청이 성공했나요? |
| 계약 | 유효한 JSON, 버전 및 예상 필드 | 응답을 활용할 수 있나요? |
| 업무 결과 | status, collections, coverage, warnings 및 meta | 요청된 범위 내에서 무엇을 알 수 있나요? |

HTTP 200 코드는 검색 검증에 충분하지 않습니다. 응답은 부분 실행이나 error 상태를 알릴 수 있습니다. 반대로 경로의 404는 빈 컬렉션을 표현하는 정상적 방법이 아닙니다: URL과 계약을 확인하세요.

## success, empty, partial, error 상태 이해하기

| 상태 | 권장 처리 방법 |
| --- | --- |
| success | 검증 후 엔터티 표시 및 한도 유지 |
| empty | 이 검색에 대해 결과가 없음을 알림 |
| partial | 사용 가능한 정보와 경고를 표시 |
| error | 검색이 불가함을 나타내고 장소 부재를 단정하지 않음 |

결과 부재는 알려진 쿼리와 소스에 국한됩니다. 이는 물리적으로 서비스가 없음을 입증하지 않습니다. 불완전한 적용 범위, 엄격한 필터 또는 한도가 결과를 줄일 수 있습니다.

## 인터페이스를 위한 의사결정 트리

```
1. La requête a-t-elle abouti ?
   Non → indisponibilité réseau ou délai dépassé.
2. Le statut HTTP est-il acceptable selon le contrat ?
   Non → traiter le code et le message d'erreur.
3. Le JSON respecte-t-il le schéma attendu ?
   Non → réponse inexploitable, jamais "aucun résultat".
4. Le statut métier est-il error ?
   Oui → recherche indisponible.
5. Le statut est-il partial ou la couverture limitée ?
   Oui → résultats utilisables + avertissement.
6. La collection attendue est-elle vide ?
   Oui → aucun résultat retourné dans ce périmètre.
   Non → afficher les résultats et leurs limites.
```

## 매개변수를 올바른 순서로 확인

먼저 위도와 경도, 순서 및 얻은 도시를 확인하고, 반경 단위와 필터 용어를 검증하세요. Services API는 types=toilets를 사용하고, 지도 URL은 modes=toilets를 사용합니다. 이들은 서로 다른 계약에 속합니다.

그다음 한 차원씩 확장하세요: 경로 한도 내에서 반경을 늘리거나 특정 필터를 제거해 명확한 테스트를 수행하세요. 초기 요청 기록을 유지하고 자동 확장 시에는 사용자에게 새 범위를 알려야 합니다.

[GPS 좌표를 중심으로 API 검색 구축하기](https://www.roote.ai/ko/guides/api%EB%A1%9C-%EA%B7%BC%EC%B2%98-%EA%B5%90%ED%86%B5-%EC%A0%95%EB%A5%98%EC%9E%A5-%EA%B2%80%EC%83%89%ED%95%98%EB%8A%94-%EB%B0%A9%EB%B2%95/)

## 다른 소스를 잃지 않고 비가용 소스 처리하기

부분 응답은 한 소스가 실패했어도 다른 소스에서 응답한 장소를 포함할 수 있습니다. 이 결과, 출처 및 적절한 경고를 유지하세요. 목록을 완전한 것으로 제시하지 말고, 누락된 필드를 잘못된 기본값으로 대체하지 마세요.

캐시에 보관된 오래된 정보도 정책이 허용하면 유용할 수 있습니다. 이 정보는 반드시 오래된 것으로 식별되어야 합니다. 요청 시각이 원래 관측 시각을 갱신하지 않습니다.

## 메시지 및 재시도 조정하기

| 상황 | 인터페이스에 맞는 메시지 | 조치 |
| --- | --- | --- |
| empty | 이 영역과 필터에 대해 반환된 결과가 없습니다 | 영역 또는 필터 수정 |
| partial | 일부 결과는 있으나 검색이 불완전합니다 | 결과와 경고 표시 |
| 검증 오류 | 검색에 잘못된 매개변수가 포함되어 있습니다 | 요청 수정 |
| 인증 또는 권한 | 이 접근은 해당 검색을 허용하지 않습니다 | 계정 또는 토큰 확인 |
| 한도 또는 비가용 | 검색이 일시적으로 불가능합니다 | 재시도 지침 준수 |

429 오류는 서비스 지침과 가능하다면 Retry-After 헤더를 확인하세요. 400 오류는 인수 수정을 요구하며 반복 요청으론 해결되지 않습니다. 사용자가 토큰을 제공했다면 401을 자동 익명 호출로 전환하지 마세요.

[ROOTE API 오류 참고](https://doc.roote.ai/roote-api/errors)

[ROOTE 서비스 상태](https://status.roote.ai/)

## 게시 전에 네 가지 상태 테스트하기

완전, 빈, 부분, 오류 응답과 함께 유효하지 않은 JSON 및 타임아웃 테스트를 준비하세요. 표시 메시지, 보존 결과 및 재시도 횟수를 확인하세요. 핵심 테스트는 장애 발생 시 서비스 부재를 주장하지 않는 것입니다.

[이 규칙을 AI 어시스턴트에 적용하기](https://www.roote.ai/ko/guides/%EC%A3%BC%EC%86%8C-%EC%A3%BC%EB%B3%80-%EA%B5%90%ED%86%B5-%EB%AA%A8%EB%B9%8C%EB%A6%AC%ED%8B%B0-%EC%B0%BE%EA%B8%B0-%EB%8F%84%EC%9A%B0%EB%AF%B8-%EB%A7%8C%EB%93%9C%EB%8A%94-%EB%B2%95/)

[모빌리티 데이터 형식 이해하기](https://www.roote.ai/ko/guides/gtfs-gtfs-rt-gbfs-%EC%B0%A8%EC%9D%B4%EC%A0%90/)

## 자주 묻는 질문

### 빈 목록이 화장실 부재를 증명하나요?

아니요. 해당 검색과 조회한 소스에 대한 결과가 없을 뿐입니다.

### 부분 응답을 표시해도 되나요?

네, 사용된 엔터티가 유효하고 필요한 경고와 한도를 유지한다면 가능합니다.

### 모든 오류를 재시도해야 하나요?

아니요. 매개변수나 접근 오류는 수정하고, 일시적 문제는 재시도를 제한하며 서비스 지침을 준수하세요.