# Không có kết quả hoặc lỗi API: làm thế nào để phân biệt?

> Phân biệt kết quả rỗng, phản hồi một phần và lỗi API ROOTE. Kiểm tra tọa độ, bộ lọc, phạm vi bao phủ và giới hạn để hiển thị thông điệp phù hợp.

Source: https://www.roote.ai/vi/guides/khong-co-ket-qua-hay-loi-api-lam-the-nao-de-phan-biet/
Language: vi
Author: ROOTE

API không có kết quả và API lỗi yêu cầu xử lý khác nhau. Một tìm kiếm thành công có thể không trả về địa điểm nào trong phạm vi xem xét. Lỗi mạng, vượt giới hạn hoặc nguồn không khả dụng ngăn không thể kết luận từ tìm kiếm.

Với ROOTE, kiểm tra phản hồi HTTP rồi trạng thái nghiệp vụ, bộ sưu tập mong đợi và phạm vi bao phủ. Cách này tránh hiển thị “không có nhà vệ sinh” khi gọi dịch vụ thất bại hoặc “không có điểm dừng” sau khi hết thời gian chờ.

## Đọc ba cấp độ của một phản hồi

| Cấp độ | Cần kiểm tra | Kết luận khả thi |
| --- | --- | --- |
| Giao vận | Kết nối, thời gian chờ và trạng thái HTTP | Yêu cầu có thành công? |
| Hợp đồng | JSON hợp lệ, phiên bản và trường mong đợi | Phản hồi có thể sử dụng được không? |
| Kết quả nghiệp vụ | trạng thái, bộ sưu tập, phạm vi bao phủ, cảnh báo và meta | Biết được gì trong phạm vi yêu cầu? |

Mã HTTP 200 không đủ để xác nhận tìm kiếm. Phản hồi có thể báo thực thi một phần hoặc trạng thái lỗi. Ngược lại, 404 trên đường dẫn không phải cách bình thường để biểu thị bộ sưu tập rỗng: kiểm tra URL và hợp đồng.

## Hiểu success, empty, partial và error

| Trạng thái | Xử lý đề xuất |
| --- | --- |
| success | Hiển thị các thực thể sau khi xác thực và giữ các giới hạn |
| empty | Thông báo không có kết quả cho tìm kiếm này |
| partial | Hiển thị thông tin có thể dùng kèm cảnh báo |
| error | Xem như tìm kiếm không khả dụng; không kết luận không có địa điểm |

Không có kết quả liên quan đến yêu cầu và nguồn đã biết. Điều này không chứng minh không có dịch vụ vật lý. Phạm vi không đầy đủ, bộ lọc hạn chế hoặc giới hạn áp dụng có thể giảm kết quả.

## Cây quyết định cho giao diện của bạn

```
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.
```

## Kiểm tra tham số theo thứ tự đúng

Trước tiên kiểm tra vĩ độ và kinh độ, thứ tự và thành phố nhận được. Tiếp theo kiểm tra đơn vị bán kính và ngôn ngữ bộ lọc. API Services dùng types=toilets; URL bản đồ dùng modes=toilets. Các tham số này thuộc các hợp đồng khác nhau.

Sau đó mở rộng từng chiều: tăng bán kính trong giới hạn đường đi hoặc bỏ bộ lọc để kiểm tra rõ ràng. Ghi lại truy vấn ban đầu. Nếu mở rộng tự động, thông báo phạm vi mới cho người dùng.

[Xây dựng truy vấn API quanh tọa độ GPS](https://www.roote.ai/vi/guides/cach-tim-kiem-tram-diem-giao-thong-gan-day-voi-api/)

## Xử lý nguồn không khả dụng mà không mất các nguồn khác

Phản hồi một phần có thể chứa các địa điểm từ nguồn đã trả lời trong khi nguồn khác thất bại. Giữ các kết quả đó, ghi nhận nguồn và cảnh báo tương ứng. Không trình bày danh sách là đầy đủ và không thay thế trường thiếu bằng giá trị mặc định gây hiểu nhầm.

Thông tin cũ trong bộ nhớ đệm cũng có thể hữu ích nếu chính sách của bạn cho phép sử dụng tạm thời. Cần ghi nhận là thông tin cũ. Thời điểm nhận truy vấn không làm mới dữ liệu gốc.

## Điều chỉnh thông điệp và xử lý lại

| Tình huống | Thông điệp cần điều chỉnh cho giao diện bạn | Hành động |
| --- | --- | --- |
| empty | Không có kết quả trả về trong khu vực này với bộ lọc này | Thay đổi khu vực hoặc bộ lọc |
| partial | Một số kết quả khả dụng; tìm kiếm chưa đầy đủ | Hiển thị kết quả và cảnh báo |
| Lỗi xác thực | Tìm kiếm có tham số không hợp lệ | Sửa truy vấn |
| Xác thực hoặc quyền | Quyền truy cập này không cho phép tìm kiếm này | Kiểm tra tài khoản hoặc mã token |
| Giới hạn hoặc không khả dụng | Tìm kiếm tạm thời không khả dụng | Tuân thủ hướng dẫn xử lý lại |

Với lỗi 429, xem hướng dẫn dịch vụ và Retry-After nếu có. Lỗi 400 đòi hỏi sửa tham số; lặp lại truy vấn không giải quyết. Không tự động biến 401 thành gọi ẩn danh nếu người dùng đã cung cấp token.

[Tham chiếu lỗi API ROOTE](https://doc.roote.ai/roote-api/errors)

[Tình trạng các dịch vụ ROOTE](https://status.roote.ai/)

## Kiểm tra bốn trạng thái trước khi phát hành

Chuẩn bị các phản hồi thử đầy đủ, rỗng, một phần và lỗi, cùng JSON không hợp lệ và thời gian chờ vượt quá. Kiểm tra thông báo hiển thị, kết quả giữ lại và số lần thử lại. Kiểm tra quan trọng là sự cố không bao giờ xác nhận không có dịch vụ.

[Áp dụng quy tắc này cho trợ lý AI](https://www.roote.ai/vi/guides/cach-tao-tri-tro-vien-tim-phuong-tien-xung-quanh-dia-chi/)

[Hiểu các định dạng dữ liệu di động](https://www.roote.ai/vi/guides/gtfs-gtfs-rt-va-gbfs-su-khac-nhau-nhu-the-nao/)

## Các câu hỏi thường gặp

### Danh sách rỗng chứng minh không có nhà vệ sinh?

Không. Chỉ cho biết không có kết quả trả về cho truy vấn và nguồn đã kiểm tra.

### Có thể hiển thị phản hồi một phần không?

Có, nếu thực thể sử dụng hợp lệ và giữ cảnh báo cùng giới hạn cần thiết.

### Có cần thử lại mỗi lỗi không?

Không. Sửa lỗi tham số hoặc quyền truy cập; giới hạn thử lại với sự cố tạm thời và tuân thủ hướng dẫn dịch vụ.