【ITニュース解説】UX for NHTSA Decode Timeouts and Partial JSON

Web上のアプリケーション、特に車両識別番号（VIN）をデコードするツールのようなものは、多くの裏側のシステムと連携して動作する。私たちがウェブサイトでVINを入力し、その車両の情報を取得しようとする際、その裏側では、私たちの入力したVINが政府機関であるNHTSA（アメリカ合衆国運輸省道路交通安全局）のような外部のAPI（Application Programming Interface）に送られ、そこでデコード処理が行われ、結果が返ってくるという一連の流れがある。しかし、このような外部のAPIを利用する際には、常にスムーズに情報が手に入るわけではない。むしろ、通信の遅延や、データの一部が欠けているなど、さまざまな「うまくいかない」状況に直面することが一般的である。

このような状況で重要なのは、単に「エラーが発生しました」と一括りにするのではなく、何が原因でうまくいかなかったのかをユーザーに正確に伝えることである。例えば、VINの入力形式が間違っている場合、これはユーザーがVINを修正すれば解決する問題であり、ネットワークの状況は関係ない。しかし、NHTSAのサーバーが混雑していて応答が遅い、あるいは一時的に到達できないという理由で情報が取得できない場合、これはユーザーのVINが間違っているわけではない。もしシステムがこれらを区別せず、すべて「VINが無効です」と表示してしまうと、ユーザーは自分のVINが正しいにもかかわらず間違っていると誤解し、システムへの信頼を失ってしまう。また、AIが自動で情報を収集する際にも、誤ったエラーメッセージはデータの品質を損なう原因となる。

システムが区別すべき失敗モードはいくつかある。まず、VINの桁数や形式といった入力値がそもそも不正である場合、これはネットワークへの問い合わせすら不要であり、クライアント側で即座にエラーを指摘できる。次に、NHTSAからの応答が規定時間内に得られない「タイムアウト」の状態がある。これはNHTSAのサーバーが一時的に遅いか、あるいは何らかの理由で到達できないことを意味する。さらに、HTTPステータスコードが429（Too Many Requests）や5xx（Server Error）である場合、これはNHTSA側が一時的にリクエストを受け付けられない状態である。また、応答自体はあったものの、その内容が不完全なJSONデータである場合もある。これは通信経路の途中でデータが途切れてしまった可能性を示唆している。そして最も複雑なのが、HTTP 200 OKという成功を示すステータスコードが返ってきたにもかかわらず、デコード結果のフィールドが一部空であったり、あるいはエラーコードやエラーメッセージが含まれていたりするケースである。これはデコード自体は行われたものの、情報の一部が不明であるか、完全に一致するデータが見つからなかったことを意味する。これらの異なる失敗を明確に区別し、それぞれに合ったUI表示をユーザーに提供することが、混乱を防ぎ、信頼性を高める上で極めて重要である。

特にタイムアウトの処理はシステムの応答性にとって肝となる。ユーザーが快適に待てる時間は限られており、対話型のVINデコードであれば8秒から15秒程度が一般的な許容範囲である。この時間を超えても応答がない場合、システムは「タイムアウト」として処理する。この際、過去のリクエストが遅れて応答してきたときに、すでに別のVINが入力されている表示を上書きしてしまう「ゾンビフェッチ」を防ぐために、AbortControllerのような機能を使って、古いリクエストを明示的にキャンセルする必要がある。ユーザーには、単に「エラー」と表示するのではなく、「NHTSAを確認中...」といった待機メッセージを表示し、タイムアウト時には「NHTSAが時間内に応答しませんでした。しばらくしてからもう一度お試しください。」といった具体的なメッセージを提示することが望ましい。このとき、タイムアウトを「このVINは無効です」と誤って伝えることは絶対にしてはならない。また、新しいVINの検索が始まった瞬間には、直前の検索結果を画面からクリアするか、古い情報であることを明示的に示すべきである。

不完全なJSONや、途中で途切れてしまった応答データへの対応も同様に重要である。ネットワークの状態が不安定な場合や、APIゲートウェイの動作によっては、データが途中で途切れてしまい、JSONとして正しく解析できないことがある。システムはこの状況を「車両が不明」というエラーとして扱うのではなく、通信上の問題、つまり「不完全な応答」としてユーザーに伝えるべきである。具体的には、JSONを解析する前に、HTTPのContent-Typeヘッダとステータスコードを確認し、JSONの解析に失敗した場合には「不完全な応答」として再試行を促す。もしJSONの解析は成功したものの、期待されるデコード結果（例：Results配列）が空であったり欠落していたりする場合には、「デコード結果がありません」と明示的に表示し、システムが勝手にデフォルト値を補完して表示するべきではない。さらに、デコード結果の一部フィールドが空文字列で返ってくる場合もよくある。この場合も、空文字列をnullとして扱い、UI上では「未提供」や「情報なし」といった形で明確に表示することが求められる。メーカーやモデル年は判明したが、トリムや製造工場が不明という状況は頻繁に発生するため、システムは判明している情報だけを表示し、不明な部分はプレースホルダーや「未提供」と表示して、情報を正直に提示するべきである。

このような多様な状態をシステムが適切に管理し、UIに反映させるためには、内部的な状態管理を明確に定義することが重要である。例えば、TypeScriptの「判別可能なユニオン型」のような仕組みを使うと、システムが現在「アイドル状態」なのか、「VINを検証中」なのか、「情報を読み込み中」なのか、あるいは「タイムアウト」や「通信エラー」、「デコード済み」、そして「無効なVIN」といった状態のどれに属しているのかを厳密に定義できる。これにより、それぞれの状態に応じて、表示すべき情報やメッセージが明確になり、アプリケーション全体の整合性が保たれる。具体的な実装では、外部APIとの通信を行う関数が、現在のVINの状態、発生したエラーの種類、あるいはデコードされた結果など、それぞれの状態に応じた具体的な情報を含むオブジェクトを返すように設計する。この仕組みは、ユーザーインターフェースがシステムの状態を正確に反映し、ユーザーに混乱を与えないようにするために不可欠である。

デコードが成功し、情報が表示される場合でも、完全な情報が揃っていないという状況を正直にユーザーに伝える姿勢が重要である。例えば、あるVINのメーカー、モデル、モデル年は表示できたが、トリムや特定の詳細情報が「未提供」である場合、それらを隠蔽するのではなく、UI上で明確に「未提供」と表示する。NHTSAからのエラーメッセージや警告文が含まれている場合も、これらを隠さずに、デコード結果のテーブルの上部などに表示すべきである。また、「この属性情報はNHTSA vPICから取得されたものであり、一部不完全な場合があります」といった補足情報を添えることで、ユーザーは表示されている情報の限界を理解し、より信頼を置くことができる。

システム障害時やタイムアウト時に自動で再試行をかけることは、ユーザー体験を向上させる上で有効な手段であるが、その実施方法には注意が必要である。タイムアウトや503のようなサーバーエラーに対しては、一度だけ自動で再試行を行うのが現実的である。それ以上の自動再試行は、ユーザーを待たせる時間が長くなりすぎるため、システムは一旦停止し、ユーザーに手動での再試行を促すべきである。再試行中は、ユーザーに「まだNHTSAを待っています」といったメッセージを表示し、同じVINでリクエストが継続していることを伝える。そして、もしユーザーがその間に新しいVINを入力した場合、現在実行中のリクエストは直ちにキャンセルし、新しいVINの処理を優先する必要がある。最も重要なのは、古いVINに対する遅延応答が、新しいVINが表示されている画面に誤って反映されてしまわないよう、応答が返ってきたVINと現在表示すべきVINが一致しているかを必ず確認することである。

まとめると、VINデコードツールのような外部APIを利用するシステムを構築する際には、タイムアウト、不完全なJSON、部分的なデータといった多様な失敗モードを「エラー」という一言で片付けず、それぞれを明確に区別し、ユーザーに正直に伝えることが非常に重要である。適切なタイムアウトを設定し、不要なリクエストはキャンセルする。受信したJSONデータは防御的に解析し、データが欠けている場合にはそれを正直に伝える。そして、「NHTSAが遅い」という状況を「このVINは存在しない」と混同してユーザーに伝えるべきではない。正直に部分的な情報を提供するUIは、偽りの完全なデコード結果よりも、ユーザーからの信頼を築き、より良いユーザー体験を提供するのである。