# 无结果或API错误：如何区分？

> 区分无结果、部分响应和ROOTE API错误。检查坐标、筛选条件、覆盖范围和限制，显示正确的提示信息。

Source: https://www.roote.ai/zh/guides/api-no-result-vs-error-chinese/
Language: zh
Author: ROOTE

没有结果的API和返回错误的API需要不同处理。一次成功搜索可能在查询范围内无任何地点返回。而网络错误、限制达成或源不可用则不能根据搜索结果得出结论。

对于ROOTE，先检查HTTP响应，再检查业务状态、预期集合和覆盖范围。该流程避免在服务调用失败时显示“无厕所”，或在超时后显示“无停靠点”。

## 解读响应的三个层级

| 层级 | 需检查内容 | 可能结论 |
| --- | --- | --- |
| 传输层 | 连接、超时和HTTP状态 | 请求成功吗？ |
| 合约层 | 有效JSON，版本和预期字段 | 响应可用吗？ |
| 业务层 | 状态、集合、覆盖、警告和元信息 | 查询范围内有什么信息？ |

HTTP 200不代表搜索有效。响应可能显示部分执行或错误状态。相反，路由的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.
```

## 按正确顺序验证参数

先检查纬度和经度、顺序及返回城市。再核对半径单位和筛选词汇。API服务用types=toilets，地图URL用modes=toilets。这些参数属于不同合约。

接着逐维度放宽范围：增加半径至路径限制内，或取消过滤做明确测试。保留初始请求记录。如自动扩展，请告知用户新范围。

[基于GPS坐标构建API搜索](https://www.roote.ai/zh/guides/remen-zhao-ji-fu-jin-de-jiao-tong-zhan-dian-yong-api-sou-suo/)

## 处理数据源不可用时不影响其他源

部分响应可含有响应源的地点信息，另一源失败时仍保留这些结果、归属和相关警告。不要将列表视为完整，亦勿用默认值替代缺失字段误导用户。

如果策略允许，缓存的过时信息也可用，但须标识为过时。请求接收时间不会刷新原始观测时间。

## 调整消息和恢复机制

| 情况 | 需在界面调整的提示信息 | 操作建议 |
| --- | --- | --- |
| 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/zh/guides/create-mobility-assistant-around-address/)

[理解出行数据格式](https://www.roote.ai/zh/guides/gtfs-gtfs-rt-et-gbfs-quelles-differences/)

## 常见问题

### 空列表证明没有厕所吗？

否。仅表示该搜索及数据源未返回结果。

### 能否展示部分响应？

可以，前提是实体有效且保留警告及限制。

### 所有错误都需重试吗？

不。需修正参数或访问错误；重试仅限暂时性故障并遵循服务指令。