JavaScriptのfetchでAPIを呼ぶ|POST・エラー処理・タイムアウト
Web API からデータを取ってくる JavaScript の関数が fetch です。書き方は短いのですが、「404 なのに catch に来ない」「response.json() でエラーになる」「別のポートの API を呼んだら失敗した」など、つまずきやすい点がいくつもあります。
この記事では、自分の PC だけで動く練習用 API サーバーを Python で立て、GET・POST、エラーの見分け方、タイムアウト、CORS エラーまでを実行結果つきで解説します。結果は Microsoft Edge 156(156.0.4314.42)のヘッドレスモードで確かめたもので、時間は環境で少し変わります。Promise と await の基本は「JavaScriptの非同期処理入門」を参照してください。
fetch とは:API に HTTP リクエストを送る関数
fetch(URL, オプション) は、ブラウザーから HTTP リクエストを送り、結果を Promise(あとで結果を渡す約束)で返す関数です。メソッドやステータスコードの意味は「REST APIとは?」を参照してください。
準備:練習用の API サーバーを自分の PC で動かす
練習には、Python の標準ライブラリだけで、わざと 404・500・遅い応答・壊れた JSON を返すサーバーを作ります。作業用のフォルダー(例:fetch-practice)に、次の内容を server.py という名前の UTF-8 で保存します。
import json
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
TODOS = [
{"id": 1, "title": "牛乳を買う", "done": False},
{"id": 2, "title": "fetch を覚える", "done": True},
]
PAGE = "<!DOCTYPE html><meta charset='utf-8'><title>fetch practice</title><h1>fetch practice</h1>"
class Handler(BaseHTTPRequestHandler):
def send(self, status, body, content_type="application/json; charset=utf-8", delay=0):
if not isinstance(body, str):
body = json.dumps(body, ensure_ascii=False)
data = body.encode("utf-8")
self.send_response(status)
self.send_header("Content-Type", content_type)
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.flush()
time.sleep(delay) # 本文だけ遅らせる
self.wfile.write(data)
def do_GET(self):
print(self.server.server_port, "GET", self.path, "Origin:", self.headers.get("Origin"), flush=True)
if self.path == "/":
self.send(200, PAGE, "text/html; charset=utf-8")
elif self.path == "/api/todos":
self.send(200, TODOS)
elif self.path == "/api/error":
self.send(500, {"error": "サーバー内部のエラー"})
elif self.path == "/api/slow":
time.sleep(5) # わざと 5 秒待ってから返す
try:
self.send(200, {"message": "5 秒かかりました"})
except ConnectionError:
print("返そうとしたら、接続はもう切られていました", flush=True)
elif self.path == "/api/slow-body":
self.send(200, TODOS, delay=2) # ヘッダーはすぐ、本文は 2 秒後
elif self.path == "/api/broken":
self.send(200, "<!DOCTYPE html><h1>メンテナンス中</h1>", "text/html; charset=utf-8")
else:
self.send(404, {"error": "見つかりません"})
def do_POST(self):
content_type = self.headers.get("Content-Type", "")
length = int(self.headers.get("Content-Length", 0))
raw = self.rfile.read(length)
print(self.server.server_port, "POST", self.path, "Content-Type:", content_type,
"本文:", raw.decode("utf-8", "replace"), flush=True)
if self.path != "/api/todos":
self.send(404, {"error": "見つかりません"})
elif not content_type.startswith("application/json"):
self.send(415, {"error": f"Content-Type は application/json にしてください(受け取ったのは {content_type})"})
else:
try:
item = json.loads(raw)
except json.JSONDecodeError:
self.send(400, {"error": "JSON として読めません"})
return
created = {"id": len(TODOS) + 1, "title": item.get("title"), "done": False}
self.send(201, created)
def log_message(self, format, *args):
pass # 標準のアクセスログは出さない
if __name__ == "__main__":
# 8152 は CORS を試すための「別オリジン」(ポートが違うと別オリジン)
other = ThreadingHTTPServer(("127.0.0.1", 8152), Handler)
threading.Thread(target=other.serve_forever, daemon=True).start()
main = ThreadingHTTPServer(("127.0.0.1", 8151), Handler)
print("http://127.0.0.1:8151/ で待ち受け中(Ctrl+C で終了)", flush=True)
try:
main.serve_forever()
except KeyboardInterrupt:
print("終了しました")
| パス | 返すもの |
|---|---|
/api/todos | GET:ToDo の配列(JSON)。POST:JSON を受け取って 201 |
/api/error | 500(サーバー内部のエラー) |
/api/slow | 5 秒待ってから 200 |
/api/slow-body | ヘッダーはすぐ、本文は 2 秒後 |
/api/broken | 200 だが中身は HTML(JSON ではない) |
| それ以外 | 404(見つかりません) |
127.0.0.1 で待ち受けるので、ほかの PC からはつながりません。ポート 8152 は CORS を試すための「別のサーバー」役です。
- エクスプローラーで作業用フォルダーを開き、アドレス欄に
powershellと入力して Enter キーを押します。 - 開いた PowerShell で次のコマンドを実行します。「http://127.0.0.1:8151/ で待ち受け中(Ctrl+C で終了)」と表示されれば起動しています。
py server.py
- Edge か Chrome のアドレス欄に次の URL を入力して開きます。「fetch practice」と表示されます。
http://127.0.0.1:8151/
- F12 キーを押し、開いた開発者ツールの上部の「Console(コンソール)」タブを選びます。
- この記事のコードを貼り付けて Enter キーを押します。次のコードを試す前に F5 キーで再読み込みすると、変数名がぶつかるエラーを防げます。
fetch("/api/todos") のように「/」で始まる URL は今開いているページと同じサーバーを指すので、必ず http://127.0.0.1:8151/ を開いたタブで試してください。初めて貼り付けるときに警告が出ることがありますが、知らない人から教えられたコードは絶対に貼り付けないでください。
基本:GET で JSON を受け取る(await は 2 回)
const response = await fetch("/api/todos");
console.log(response.status, response.ok);
console.log(response.headers.get("Content-Type"));
const todos = await response.json();
console.log(todos.length, todos[0].title);
200 true
application/json; charset=utf-8
2 牛乳を買う
ポイントは await が 2 回あることです(コンソールでは関数の外でも await が使えます)。1 回目の await fetch(…) で受け取るのは、ステータスコードやヘッダーの入った Response オブジェクトで、データそのものではありません。2 回目の await response.json() で本文を読み、JSON を JavaScript の配列やオブジェクトに変換します。
MDN の「Using the Fetch API」には、ブラウザーがステータスとヘッダーを受け取った時点で、本文を受け取る前でも fetch の Promise は Response で成功する、と書かれています。ヘッダーはすぐ、本文は 2 秒後に返す /api/slow-body で確かめます。
const start = performance.now();
const response = await fetch("/api/slow-body");
console.log(`fetch が完了:${((performance.now() - start) / 1000).toFixed(2)} 秒`, response.status);
const todos = await response.json();
console.log(`json() が完了:${((performance.now() - start) / 1000).toFixed(2)} 秒`, todos.length);
fetch が完了:0.00 秒 200
json() が完了:2.00 秒 2

本文は json() のほか text()(文字列のまま)でも読め、どちらも await が必要です。受け取った JSON が長くて読みにくいときは、text() の結果を「JSON整形ツール」に貼ると整えて表示できます。
Response のよく使うプロパティは、status(ステータスコードの数値)、statusText("OK" などのメッセージ)、ok(MDN の説明では、ステータスが 200〜299 なら true)、headers(get("名前") でヘッダーを読む)です。ヘッダーの種類は「HTTPヘッダーの読み方」で解説しています。
落とし穴:404 や 500 では catch に来ない
fetch で一番多い勘違いがこれです。存在しないパス(404)と、サーバーのエラー(500)を try/catch 付きで呼んでみます。
for (const url of ["/api/todos", "/api/nothing", "/api/error"]) {
try {
const response = await fetch(url);
console.log(url, response.status, response.statusText, response.ok);
} catch (error) {
console.log(url, "catch に来た:", error.message);
}
}
/api/todos 200 OK true
/api/nothing 404 Not Found false
/api/error 500 Internal Server Error false
404 も 500 も catch に来ず、普通に Response が返りました。MDN の fetch のページにも「サーバーがエラーを示すステータスコード(404、504 など)で応答しても、fetch の Promise は reject(失敗)しない。Response.ok や Response.status を確かめる必要がある」と書かれています。fetch にとっては「サーバーから返事が来た」ので成功なのです。
ok を確かめてから JSON を返す関数を作る
毎回 ok を確かめるのは忘れやすいので、関数にまとめておくと安全です。ok が false なら自分で throw して、呼ぶ側の catch に届くようにします。
async function getJSON(url) {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`HTTP ${response.status} ${response.statusText}(${url})`);
}
return response.json();
}
try {
const todos = await getJSON("/api/todos");
console.log("件数:", todos.length);
const missing = await getJSON("/api/nothing");
console.log("ここは表示されない", missing);
} catch (error) {
console.log("エラー:", error.message);
}
件数: 2
エラー: HTTP 404 Not Found(/api/nothing)
エラーのときも本文は読めます。/api/nothing の本文を json() で読むと error は「見つかりません」で、API によってはここに理由が入っています。throw の使い方は「JavaScriptのエラー処理入門」、ステータスコードの意味は「HTTPステータスコード検索」で調べられます。
catch に来るのは通信できなかったとき(TypeError: Failed to fetch)
では、どんなときに reject されるのでしょうか。サーバーを止めて確かめます。PowerShell の画面で Ctrl+C キーを押してサーバーを止め、ページを再読み込みせずに、同じタブのコンソールで次を実行します。
try {
const res = await fetch("/api/todos");
console.log(res.status);
} catch (error) {
console.log(error.name + ": " + error.message, error instanceof TypeError);
}
TypeError: Failed to fetch true
今度は catch に来て、TypeError: Failed to fetch(取得に失敗した)になりました。MDN では TypeError になる理由として、URL が正しくない、ネットワークのエラーなどが挙げられています(文言は Edge のもので、ブラウザーにより違うことがあります)。確かめたら py server.py でサーバーを起動し直します。
| 状況 | fetch の結果 | 見分け方 |
|---|---|---|
| 200 番台 | 成功(Response) | response.ok が true |
| 404・500 など | 成功(Response) | response.ok が false |
| サーバーが止まっている・ネットワークがない | 失敗(TypeError) | catch に来る |
| CORS で許可されていない | 失敗(TypeError) | catch に来る(後述) |
| AbortController・タイムアウトで中止 | 失敗(AbortError・TimeoutError) | error.name(後述) |
POST で JSON を送る
データを送るときは、第 2 引数のオプションに method・headers・body を指定します。
const response = await fetch("/api/todos", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ title: "記事を書く" }),
});
console.log(response.status, response.statusText);
const created = await response.json();
console.log(created.id, created.title, created.done);
201 Created
3 記事を書く false
method:省略すると GET。送るときは"POST"などheaders:本文の形式をContent-Typeでサーバーに伝えるbody:送る本文。オブジェクトはJSON.stringifyで JSON の文字列にしてから渡す(詳しくは「JavaScriptのJSON.parseとstringify」)
Content-Type を付け忘れると 415 になる
上のコードから headers の行だけを消して送ると、結果は次のようになりました。
415 Unsupported Media Type
Content-Type は application/json にしてください(受け取ったのは text/plain;charset=UTF-8)
本文が文字列のとき、fetch は Content-Type を text/plain;charset=UTF-8 にして送ります(サーバー側の表示で確認)。中身は JSON でも、サーバーは「JSON ではない」と判断して 415 を返しました。「HTTPヘッダーの読み方」の実例 2(curl で付け忘れた例)と同じ失敗です。400 を返すサーバーもあります。
JSON.stringify を忘れると「[object Object]」が届く
body: { title: "記事を書く" } のようにオブジェクトのまま渡すと、エラーにはならずに送信され、サーバーには次のように届きました(PowerShell の画面の表示)。
8151 POST /api/todos Content-Type: application/json 本文: [object Object]
MDN にあるとおり、オブジェクトは toString() で文字列にされるためです。サーバーは 400(JSON として読めません)を返しました。
本文は 1 回しか読めない(body stream already read)
デバッグのつもりで json() を 2 回呼ぶと、2 回目でエラーになります。
const response = await fetch("/api/todos");
console.log((await response.json()).length);
try {
console.log(await response.json());
} catch (error) {
console.log(error.name + ": " + error.message);
}
2
TypeError: Failed to execute 'json' on 'Response': body stream already read
本文はストリーム(流れてくるデータ)なので、一度読むと読めません(response.bodyUsed が false から true になります)。2 回読みたいときは、MDN にあるとおり読む前に response.clone() で複製するか、json() の結果を変数に入れて使い回します。
JSON でないものが返ると SyntaxError
メンテナンス中のページなど、200 なのに HTML が返る /api/broken を json() で読んでみます。
const response = await fetch("/api/broken");
console.log(response.status, response.ok, response.headers.get("Content-Type"));
try {
const data = await response.json();
} catch (error) {
console.log(error.name + ": " + error.message);
}
200 true text/html; charset=utf-8
SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
ok は true なのに、json() が SyntaxError で失敗しました。「Unexpected token ‘<‘」は、受け取ったのが HTML だという合図です(URL の間違い、ログイン画面が返った など)。Content-Type が application/json で始まるかを確かめてから json() を呼び、原因は text() で中身を見て調べます。
タイムアウト:AbortSignal.timeout と AbortController
fetch には「何秒で諦める」という設定が初めからありません。サーバーが返事をしないと、ずっと待ち続けます。制限時間を付けるには signal オプションに AbortSignal.timeout(ミリ秒) を渡します。5 秒かかる /api/slow を 2 秒で打ち切ります。
const start = performance.now();
try {
const response = await fetch("/api/slow", { signal: AbortSignal.timeout(2000) });
console.log(response.status);
} catch (error) {
console.log(error.name, error.message);
}
console.log(`${((performance.now() - start) / 1000).toFixed(2)} 秒`);
TimeoutError signal timed out
2.00 秒
約 2 秒(実測 2.00 秒・2.02 秒)で、MDN の説明どおり TimeoutError になりました。
「キャンセル」ボタンなどで止めるときは AbortController を使います。new AbortController() の signal を fetch に渡し、1 秒後に abort() を呼ぶと、約 1 秒で AbortError(signal is aborted without reason)になりました。error.name が TimeoutError か AbortError かで、時間切れか自分で止めたかを区別できます。
注意したいのは、止まるのはブラウザー側の待ちだけということです。サーバーは 5 秒後に最後まで処理し、PowerShell に「返そうとしたら、接続はもう切られていました」と表示されました。POST がタイムアウトしてもサーバー側では登録が済んでいることがあり、すぐ再送すると二重登録のおそれがあります。
別のポートの API を呼ぶと CORS エラーになる
ポートが違うと、ブラウザーは別のサイト(別オリジン)として扱います。8151 のページから、8152 のサーバーを呼んでみます。
try {
const response = await fetch("http://127.0.0.1:8152/api/todos");
console.log(response.status);
} catch (error) {
console.log(error.name + ": " + error.message);
}
TypeError: Failed to fetch
JavaScript に届くのはサーバー停止のときと同じ TypeError: Failed to fetch だけですが、コンソールには赤い字で次のメッセージが出ました。
Access to fetch at 'http://127.0.0.1:8152/api/todos' from origin 'http://127.0.0.1:8151' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
PowerShell には 8152 GET /api/todos Origin: http://127.0.0.1:8151 と表示され、リクエストはサーバーに届いています。返事に Access-Control-Allow-Origin ヘッダーがないので、ブラウザーが JavaScript に読ませなかったのです。直すのはサーバー側の設定で、仕組みは「CORSとは?」で解説しています。
XMLHttpRequest との違い
古いコードでは XMLHttpRequest(XHR)をよく見かけます。new XMLHttpRequest() を作って open("GET", "/api/todos")・send() し、load イベントで結果を受け取る書き方で、同じ API から同じ 2 件を受け取れました。
違いは、結果をイベントのコールバックで受け取るか(XHR)、Promise で受け取って await できるか(fetch)です。404 でも load イベントが来て status が 404 になり、エラーを自分で判断する点は同じでした。新しく書くなら fetch で十分です。
API キーをフロントエンドの JavaScript に書かない
headers: { "Authorization": "Bearer 本物のキー" } のように、API キーをブラウザーで動く JavaScript に書いてはいけません。ブラウザーで動くコードと送ったリクエストは、開発者ツールで誰でも見られるからです。抜き取られたキーで API を使われ、料金を請求されるおそれがあります。
秘密のキーが必要な API は、自分のサーバー側から呼び、ブラウザーは自分のサーバーにだけ fetch します。キーはサーバーの環境変数などに置きます(「.envと環境変数で秘密情報を守る」参照)。
よくある質問
Python からも同じ API を呼べますか?
呼べます。CORS の制限はなく、urllib では 404 などで例外が出るなど、エラーの扱いが fetch と違います(「PythonでHTTPリクエストを送る方法」)。コマンドなら「curlコマンドの使い方」も参考になります。
まとめ
await fetch()で Response、await response.json()で中身。404・500 は catch に来ないのでokを確かめる- POST は
method・Content-Type・JSON.stringifyの 3 点セット - タイムアウトは
AbortSignal.timeout()。API キーはフロントエンドに書かない
関連する記事・ツール
- JavaScriptの非同期処理入門|Promise・async/awaitの使い方
- JavaScriptのJSON.parseとstringify|エラーと消える値の注意点
- JavaScriptのエラー処理入門|try・catchとErrorの使い方
- REST APIとは?HTTPメソッド・ステータスコードの意味とcurlでの試し方
- HTTPヘッダーの読み方|リクエストとレスポンスの主なヘッダーをcurlで確かめる
- CORSとは?エラーの原因と正しい設定を2つのローカルサーバーで確かめる
- PythonでHTTPリクエストを送る方法|urllibとrequestsの使い方と例外処理
- JSON整形ツール