JavaScript APIのエラー処理｜原因別の判定と対処【JavaScript入門】

本記事にはプロモーション（アフィリエイト広告）を含みます。

APIを使った情報取得が失敗したとき、何を調べ、画面にどう伝えればよいか迷うことがあります。この記事では、失敗を種類ごとに分け、JavaScriptで確認する方法を説明します。

API（Application Programming Interface）とは、別のプログラムから機能や情報を使うための窓口です。たとえば、天気を表示するページが、天気情報を提供するサービスからデータを受け取るときに使います。

HTTP（Hypertext Transfer Protocol）は、ブラウザーと相手のコンピューターが情報をやり取りするときに使う決まりごとです。以下では、そのやり取りで返される結果を確認します。

エラー処理で大切なのは、失敗をひとまとめにしないことです。相手から返事が来たが内容が失敗を示す場合と、返事自体を受け取れない場合では、確認する場所が異なります。

APIの失敗は3種類に分けて考える

まず、何が起きたかを次の3つに分けます。

JSON（JavaScript Object Notation）は、データを文字で表す形式です。APIの返事に使われることがありますが、返事がいつもJSONとは限りません。

この違いを知っておくと、通信そのものの失敗と、相手から返された失敗の結果を混同せずに済みます。

HTTPステータスは200だけでなく2xxで判定する

HTTPステータスコードは、相手から返される3桁の番号です。200番台は処理が成功したことを示し、400番台や500番台は失敗を示す場合があります。

2xxは、200から299までの番号をまとめた呼び方です。成功判定を200だけにすると、201や204も失敗として扱ってしまいます。成功かどうかを番号ひとつだけで決めず、返事の内容があるかも確認してください。

fetchでHTTPエラー・通信失敗・JSONの読み取り失敗を分ける

fetchは、JavaScriptから相手に情報を求めるための機能です。HTTPエラーの返事を受け取っただけでは、通常、それだけで処理が失敗した扱いにはなりません。返事の状態を自分で確認します。

次の例では、HTTPの失敗、返事の読み取り失敗、通信処理の失敗を、それぞれ別のメッセージに分けます。

<button id="load-button" type="button">情報を読み込む</button>
<p id="message" role="status"></p>
<pre id="result"></pre>

<script>
const button = document.getElementById("load-button");
const message = document.getElementById("message");
const result = document.getElementById("result");

button.addEventListener("click", loadData);

async function loadData() {
  button.disabled = true;
  message.textContent = "読み込み中です。";
  result.textContent = "";

  try {
    const response = await fetch(
      "https://jsonplaceholder.typicode.com/users/1"
    );

    if (!response.ok) {
      throw new Error(`HTTPエラー: ${response.status}`);
    }

    let data;

    try {
      data = await response.json();
    } catch (error) {
      throw new Error("返事をJSONとして読み取れませんでした。");
    }

    message.textContent = "読み込みました。";
    result.textContent = JSON.stringify(data, null, 2);
  } catch (error) {
    console.error("情報の読み込みに失敗しました。", error);
    message.textContent =
      "情報を読み込めませんでした。接続を確認して、もう一度お試しください。";
  } finally {
    button.disabled = false;
  }
}
</script>

asyncとawaitは、返事を待ってから次の処理へ進む書き方です。try/catchは、処理中に起きた問題を受け止める書き方です。

awaitは、Promise（プロミス）の結果を待ちます。Promiseは、すぐには終わらない処理について、後から結果を受け取るための仕組みです。

responseは相手からの返事を表します。response.okがfalseなら、HTTPステータスが成功を示す範囲ではありません。そこでエラーを発生させ、catchへ処理を移しています。

response.json()は、返事の中身をJSONとして読み取ります。返事がJSONではない場合や、JSONの書き方が正しくない場合は、読み取りに失敗することがあります。

catchに入るのは通信の失敗だけではありません。fetchの処理が拒否された場合や、処理を中断した場合、上の例で発生させたHTTPエラーやJSON読み取りエラーもcatchで受け取ります。

throwは、自分で問題を発生させて、通常の処理を止める書き方です。この例では、HTTPが成功を示さないときにthrowを使っています。

コードを試す前提と期待する結果

上の例は、HTMLファイルとして保存し、JavaScriptを実行できるブラウザーで開いて使う形です。外部の接続先にアクセスするため、インターネットへの接続と、接続先がブラウザーからの要求を受け付けることが必要です。

APIの接続先は、コード中のURLで指定しています。この例は外部サービスを使うため、そのサービスが利用できることを保証するものではありません。

1. コードをHTMLファイルに保存します。
2. ブラウザーでファイルを開き、「情報を読み込む」を押します。
3. 成功した場合は、読み込み完了の案内と、受け取った情報が表示されます。
4. 失敗した場合は、利用者向けの案内が表示されます。詳しい情報は開発者向けのコンソールに記録されます。

上記は期待する結果の説明であり、この環境で実行した検証結果ではありません。ブラウザー名・バージョン、実行日、接続先の応答を確認してから、掲載用の実行結果として確定してください。

XMLHttpRequestでの成功判定とエラー処理

XMLHttpRequest（エックスエムエル・エイチティーティー・リクエスト）は、JavaScriptから情報を送受信する機能です。略してXHRと呼ばれます。fetchとは別の書き方ですが、HTTPエラーの返事が来た場合にも、返事の状態を確認して処理します。

const xhr = new XMLHttpRequest();

xhr.open("GET", "https://jsonplaceholder.typicode.com/users/1");

xhr.onload = () => {
  if (xhr.status >= 200 && xhr.status < 300) {
    console.log("成功:", xhr.responseText);
  } else {
    console.error("HTTPエラー:", xhr.status);
  }
};

xhr.onerror = () => {
  console.error("通信に失敗しました。");
};

xhr.ontimeout = () => {
  console.error("時間内に返事を受け取れませんでした。");
};

xhr.onabort = () => {
  console.log("処理を中断しました。");
};

xhr.timeout = 10000;
xhr.send();

onloadは、通信処理が完了したときに呼ばれます。HTTPエラーの返事でも呼ばれるため、statusが200かどうかだけでなく、200以上300未満かを確認します。

onerror、ontimeout、onabortは、それぞれ通信の失敗、制限時間を過ぎた場合、処理を中断した場合を扱います。fetchとXHRのどちらでも、HTTPステータスの確認と、返事を受け取れない場合の対応を分けて考えます。

fetchとXHRの違いを比較する

どちらを使う場合も、「返事が失敗を示す場合」と「返事を受け取れない場合」を分けて処理します。既存の仕組みがXHRを使っている場合は、動作を理解して適切に判定することが大切です。

よくある失敗と確認方法

• 404が返る：接続先の指定や、求めている情報が存在するかを確認します。
• 400が返る：送った値が接続先の求める形式になっているかを確認します。
• 401が返る：ログイン状態や、接続先が求める認証情報を確認します。
• 500が返る：相手側の処理に問題がある可能性があります。利用者に内部情報を見せず、必要に応じて管理者へ確認します。
• JSONの読み取りに失敗する：返事の内容がJSONか、内容が空ではないか、JSONを読む前提が合っているかを確認します。
• ブラウザーから接続できない：インターネット接続、接続先の設定、アクセス制限などを確認します。
• 処理が長く終わらない：読み込み中の表示と中断方法を用意し、必要なら時間制限を設定します。

CORS（Cross-Origin Resource Sharing）は、別の場所にある情報をブラウザーから受け取るときに、接続先が許可を示すための仕組みです。接続先の許可がないと、ブラウザーが返事をページのJavaScriptへ渡さないことがあります。

CORSの問題は、JavaScriptのエラー処理だけで解決できるとは限りません。利用者側で制限を無理に回避せず、接続先の管理者に許可の設定を確認してください。

画面表示・ログ・再試行で気を付けること

利用者には、次に何をすればよいかが分かる案内を表示します。たとえば「情報を読み込めませんでした。接続を確認して、もう一度お試しください」と伝えます。

エラーの詳細は開発者向けの記録に残し、画面には必要以上の情報を出さないようにします。接続先から返された内容や内部の仕組みをそのまま見せると、利用者を混乱させたり、見せる必要のない情報を公開したりするおそれがあります。

再試行ボタンは、失敗した操作を繰り返して問題がない場合に使います。データを作成・変更する処理では、再送によって同じ操作が重複する可能性があるため、結果を確認せずに自動で繰り返さないでください。

AbortController（アボート・コントローラー）は、fetchの処理を中断するために使う機能です。利用者が画面を離れた場合などに処理を止められますが、中断された処理も失敗と同じcatchへ入ることがあるため、利用者が自分で止めたのか、別の失敗なのかを区別します。

再試行や制限時間の設定は、通信先や操作の内容に合わせて決めます。すべてのエラーを同じ方法で再試行するのではなく、何が起きたかを確認してから対応してください。

公式情報と仕様を確認する

詳しい動作や使える機能は、公式の仕様と利用するブラウザーの情報を確認してください。

• WHATWG Fetch Standard：fetchの仕様
• WHATWG XMLHttpRequest Standard：XMLHttpRequestの仕様
• MDN：AbortController：中断の仕組みの解説
• MDN：HTTPレスポンスステータスコード：番号の意味の解説

この記事の例について、確認したブラウザー名・バージョン・確認日・実行結果は、現時点で人による情報が提供されていません。公開前に環境を記録し、コードと公式仕様を照合してください。