# 結果なしかAPIエラーか：どのように区別するか？

> 空の結果、部分応答、ROOTE APIエラーの違いを理解しましょう。座標、フィルター、カバレッジ、制限をチェックして正しいメッセージを表示します。

Source: https://www.roote.ai/ja/guides/api%E7%B5%90%E6%9E%9C%E3%81%AA%E3%81%97%E3%81%A8%E3%82%A8%E3%83%A9%E3%83%BC%E3%81%AE%E9%81%95%E3%81%84/
Language: ja
Author: ROOTE

結果なしのAPIとエラー発生のAPIは異なる処理を要します。成功した検索でも、対象範囲に場所が存在しないことがあります。逆にネットワークエラー、制限超過、利用不可の情報源は検索結果の確定を妨げます。

ROOTEではHTTP応答、ビジネスステータス、期待されるコレクション、カバレッジを順に検査します。この手順により、サービス呼び出し失敗やタイムアウト後に「トイレなし」や「停留所なし」と誤表示することを防ぎます。

## 応答の3つのレベルを読む

| レベル | 検証項目 | 可能な結論 |
| --- | --- | --- |
| 通信 | 接続状況、タイムアウト、HTTPステータス | リクエストは成功しましたか？ |
| 契約 | 有効なJSONか、バージョンと期待項目の有無 | 応答は活用可能か？ |
| ビジネス結果 | status、collections、coverage、warnings、meta | 要求された範囲では何が判明しているか？ |

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/ja/guides/api%E3%81%A7%E8%BF%91%E3%81%8F%E3%81%AE%E4%BA%A4%E9%80%9A%E5%81%9C%E7%95%99%E6%89%80%E3%82%92%E6%A4%9C%E7%B4%A2%E3%81%99%E3%82%8B%E6%96%B9%E6%B3%95/)

## 一部情報源の利用不可に対処しつつ他を失わない

部分応答は一部情報源からの応答を含み、他が失敗していても利用可能。結果、それらの帰属、関連警告を保持。リストを完全とせず、欠落項目を誤解させる既定値で補わない。

ポリシーが許せば、古いキャッシュ情報も有用。古い情報として明示し続けること。リクエスト受信時刻は元情報の鮮度を更新しない。

## メッセージと回復方法の適応

| 状況 | インターフェースに合わせたメッセージ | 対応策 |
| --- | --- | --- |
| empty | この範囲とフィルターで結果が見つかりませんでした | 範囲やフィルターを変更してください |
| partial | 一部結果はありますが、検索は不完全です | 結果と警告を表示する |
| 検証エラー | 検索に無効なパラメータがあります | リクエストを修正してください |
| 認証または権限不足 | このアクセスではこの検索は許可されていません | アカウントまたはトークンを確認してください |
| 制限または利用不可 | 検索は一時的に利用できません | 回復方針を遵守する |

429ならサービスの指示とRetry-Afterを参照。400は引数修正が必要で同一リクエスト繰返しでは解決しません。使用者がトークンを提供している場合、401を匿名呼び出しに自動変換しないでください。

[ROOTE APIエラーリファレンス](https://doc.roote.ai/roote-api/errors)

[ROOTEサービスの状態](https://status.roote.ai/)

## 公開前に4状態をテスト

完全、空、部分、エラー応答および無効JSONやタイムアウトを用意。表示メッセージ、保持結果、回復試行数を検証。障害時にサービス不存在を誤認させないことが最重要。

[これらのルールをAIアシスタントに適用する](https://www.roote.ai/ja/guides/%E3%82%A2%E3%83%89%E3%83%AC%E3%82%B9%E5%91%A8%E8%BE%BA%E3%81%AE%E3%83%A2%E3%83%93%E3%83%AA%E3%83%86%E3%82%A3%E3%82%A2%E3%82%B7%E3%82%B9%E3%82%BF%E3%83%B3%E3%83%88%E3%81%AE%E4%BD%9C%E3%82%8A%E6%96%B9/)

[モビリティデータフォーマットの理解](https://www.roote.ai/ja/guides/gtfs-gtfs-rt-gbfs-%E3%81%AE%E3%81%A1%E3%81%8C%E3%81%84/)

## よくある質問

### 空リストはトイレ不存在の証明か？

いいえ。この検索と参照情報源で結果がなかったことを示すだけです。

### 部分応答を表示してよいか？

はい。利用可能なエンティティが有効であり、必要な警告と制限を保持する場合は可能です。

### すべてのエラーで再試行すべきか？

いいえ。パラメータ/アクセスの誤りは修正し、一時的障害は回復回数を制限し、サービス指示を遵守してください。