FlaskでAPIのエラーハンドリングを丁寧に行う方法まとめ！初心者向けにやさしく解説

FlaskのAPIでエラーハンドリングを丁寧に行う方法まとめ

先生と生徒の会話形式で理解しよう

生徒

「FlaskでAPIを作っているときに、エラーが出てアプリが止まっちゃうことがあります。これってどうしたらいいですか？」

先生

「とても大切なポイントですね。FlaskでAPIを作るときは、エラーハンドリングという仕組みを使って、予想外のエラーに対応できるようにするのが基本です。」

生徒

「エラーハンドリングって難しそうですが、初心者でもできますか？」

先生

「もちろんです。今日はパソコン初心者でも安心して学べるように、FlaskのAPIでのエラーハンドリングをとても丁寧に説明していきますね。」

1. エラーハンドリングとは？

エラーハンドリングとは、プログラムの実行中に起きたエラーや想定外のトラブルを受け止めて、アプリが途中で止まらないようにするための仕組みです。特にAPIでは、エラーが起きたときに「何が問題だったのか」を分かりやすく返すことがとても重要になります。

たとえば、存在しないデータを取得しようとした場合に、何も対策をしていないと難しいエラー画面がそのまま表示されてしまいます。そこでエラーハンドリングを行うと、「そのデータは見つかりませんでした」や「入力内容を確認してください」といった、やさしいメッセージを返せるようになります。

プログラミング未経験の方は、エラーハンドリングを 「失敗したときの案内係」のようなものだと考えると分かりやすいです。何か問題が起きても、利用者を迷わせず、次にどうすればいいかを教えてくれます。

初心者向け：エラーハンドリングがない場合とある場合


【エラーハンドリングなし】
→ 英語のエラーが突然表示されて止まる

【エラーハンドリングあり】
→ 内容が分かるメッセージを返して処理を続ける

このように、エラーハンドリングはAPIの「安心感」を高める大切な要素です。 FlaskでAPIを作るなら、最初から意識しておくと後で困りにくくなります。

2. Flaskとは？初心者向けにおさらい

Flask（フラスク）は、PythonでWebアプリケーションやAPIを作るための とてもシンプルなフレームワークです。余計な機能が少なく、必要なものだけを自分で組み合わせて使えるのが大きな特徴です。

プログラミング未経験の方は、Flaskを 「最低限の道具だけが入った工具箱」のように考えると分かりやすいです。最初から難しい設定を覚えなくても、少ないコードでAPIを動かすことができます。

たとえば、たった数行のコードを書くと、ブラウザからアクセスできるAPIを作れます。「まず動くものを作って理解したい」という初心者にとって、Flaskはとても相性の良い選択です。

初心者向け：Flaskでできることのイメージ


・APIを作る
・ブラウザからアクセスできるページを表示する
・JSON形式でデータを返す

このように、Flaskは「WebとAPIの入口」を作る役割を持っています。その上で、エラーハンドリングを組み合わせることで、安心して使えるAPIへと成長させていくことができます。

3. Flaskの基本的なエラーハンドリングの方法

ここでは、Flaskでもっとも基本となるエラーハンドリングの書き方を確認します。 Flaskには、エラーが発生した瞬間を自動で受け取ってくれる便利な仕組みが用意されており、それを使うことで「エラー専用の対応窓口」を作ることができます。

そのときに使うのが @app.errorhandler です。これは「この番号のエラーが起きたら、この処理を実行してください」というルールをあらかじめ登録しておくための目印のようなものです。

たとえば、存在しないページにアクセスされたときの 404エラー や、サーバー内部で問題が起きたときの 500エラー を、分かりやすいメッセージに置き換えることができます。


from flask import Flask, jsonify

app = Flask(__name__)

# 通常のAPI
@app.route('/')
def index():
    return 'ようこそ！FlaskのAPIへ！'

# 404エラー（URLが存在しない場合）
@app.errorhandler(404)
def not_found(error):
    return jsonify({
        'error': 'お探しのページは見つかりませんでした。'
    }), 404

# 500エラー（サーバー側の処理で問題が起きた場合）
@app.errorhandler(500)
def server_error(error):
    return jsonify({
        'error': 'サーバー内部でエラーが発生しました。'
    }), 500

if __name__ == '__main__':
    app.run(debug=True)

初心者向け：ここでやっていること


・エラー番号ごとに対応を決めている
・エラー時もJSONで結果を返している
・アプリが途中で止まらないようにしている

このように、@app.errorhandler を使うと、エラーが起きても落ち着いて対応できるAPIを作ることができます。 Flaskでエラーハンドリングを学ぶ最初の一歩として、必ず覚えておきたい書き方です。

4. 実際にエラーを体験してみよう

ここでは、先ほど作ったFlaskアプリを実際に動かして、 エラーがどのように表示されるのかを体験してみましょう。自分の目で確認すると、エラーハンドリングの役割がより分かりやすくなります。

アプリを起動した状態で、ブラウザのアドレス欄に存在しないURL（たとえば /no-page）を入力してアクセスしてみてください。すると、次のようなJSON形式のメッセージが表示されます。


{
    "error": "お探しのページは見つかりませんでした。"
}

これは 404 Not Found と呼ばれるエラーで、「指定されたページやAPIが存在しない」ことを意味しています。先ほど設定した @app.errorhandler(404) が働き、難しいエラー画面の代わりに、分かりやすいメッセージを返してくれています。

このように、エラーをあらかじめ想定しておくことで、利用者が迷わず状況を理解できるAPIになります。エラーを体験してみることは、Flaskのエラーハンドリングを理解する近道です。

5. tryとexceptを使った個別のエラーハンドリング

次は、APIの処理の途中で起こる予期しないエラーに対して、より細かく対応する方法を見ていきましょう。ここで使うのが、Pythonの基本構文である try と except です。

try は「うまくいくはずの処理」を書く場所で、もし途中でエラーが発生した場合は、対応する except に処理が移ります。これにより、エラーが起きてもアプリ全体が止まらず、落ち着いて対処できます。

プログラミング未経験の方は、 「失敗するかもしれない処理をあらかじめ見張っておく」 イメージを持つと分かりやすいです。


from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/divide', methods=['GET'])
def divide():
    try:
        x = int(request.args.get('x'))
        y = int(request.args.get('y'))
        result = x / y
        return jsonify({'result': result})
    except ZeroDivisionError:
        return jsonify({'error': '0で割ることはできません。'}), 400
    except ValueError:
        return jsonify({'error': '数字を入力してください。'}), 400
    except Exception as e:
        return jsonify({'error': f'不明なエラー: {str(e)}'}), 500

初心者向け：このコードのポイント


・0で割ったときのエラーを個別に処理している
・数字以外が入力された場合も想定している
・想定外のエラーでも必ずメッセージを返している

このように try-except を使うと、エラーの内容ごとに適切なメッセージを返すことができます。 APIの信頼性を高めるためにも、個別のエラーハンドリングはとても重要です。

6. 上記のコードを使った動作例

次のURLにアクセスすると、それぞれの動作が確認できます。

/divide?x=10&y=2 → 正常に割り算が行われます
/divide?x=10&y=0 → 0で割ることはできませんと表示
/divide?x=abc&y=1 → 数字を入力してくださいと表示


{
    "error": "0で割ることはできません。"
}

7. JSONで返すことでAPIらしくなる

FlaskのAPIでエラーを返すときは、jsonify()という関数を使って、JSON形式で返すのが一般的です。

JSON（ジェイソン）とは、データを「キーと値のセット」で表現する形式で、Webサービスでよく使われています。

エラーをこの形式で返すと、機械でも読みやすく、他のアプリと連携しやすくなります。

8. よくあるエラーと対処法

404エラー：ページやAPIのURLが間違っている
500エラー：プログラムの中で例外が発生している
400エラー：入力されたデータに問題がある（たとえば未入力や形式違い）

それぞれのエラーに対して、@app.errorhandlerを使ったり、try-exceptで囲むことで、アプリが落ちずに丁寧に対応できます。

まとめ

FlaskでAPIを作るときにとても重要になるのが「エラーハンドリング」です。この記事では、初心者にもわかりやすいように、Flaskでのエラーハンドリングの仕組みや考え方、実際のコード例を丁寧に解説してきました。エラーハンドリングは、APIの安全性や信頼性、操作性を左右する大切な要素です。単に動作するAPIではなく、ユーザーや外部システムが安心して利用できるAPIを作るには、丁寧にエラーを処理し、必要な情報を正しく返す仕組みが欠かせません。まず、@app.errorhandlerを使ったページ単位・アプリ全体のエラーハンドリングでは、404や500といったよく発生するHTTPエラーに対して、わかりやすいJSONレスポンスを返す方法を学びました。ページが存在しないときに404エラーを返し、予期せぬエラーが起きた場合には500エラーを返して「サーバー内部でエラーが発生した」ことを知らせる実装は、API開発では基本となるパターンです。初心者でもわかりやすく、アプリ全体を守るための重要なステップです。さらに、個別の処理内で起きるエラーを細かく制御するためのtryとexceptの使い方についても具体的な例を通して学びました。「0で割る」などの予想可能なエラーや、数字でない値が送られてきた場合など、現実のAPIでは頻繁に起きる問題に対して丁寧に応答を返す方法を確認しました。これにより、より安全で柔軟なAPIを構築できるようになります。外部からの入力は常に予想外のデータが送られてくる可能性があるため、エラー時の動作をきちんと決めておくことは不可欠です。また、JSON形式でエラーを返すことの利点についても触れました。APIの世界では、機械にとって読みやすく統一された形式でデータを返すことが求められます。その際、単純な文字列やHTMLではなく、構造化されたJSONを返すことで、利用者（別のアプリやプログラム）がエラーを正しく処理できます。「何が原因で」「どの部分に問題があって」「どう直せばいいのか」という情報をJSONで返すことで、開発者にとって親切なAPIを構築できます。ここでは実際に、さらに発展的なエラーハンドリングの例として、複数のエラーをまとめて一括管理できる方法も紹介します。Flaskでは、Blueprintを使ったアプリケーション構造の分割や、クラスベースのエラーハンドリングも可能であり、規模の大きなAPI開発にも対応できます。以下に、カスタム例外を定義し、それを専用のエラーハンドラーで処理する応用的なコード例を掲載します。大規模なAPIでは、こういった設計が品質を大きく左右します。

カスタム例外を使った応用的エラーハンドリングのサンプルコード


from flask import Flask, jsonify, request

app = Flask(__name__)

# カスタム例外を定義
class InvalidUsage(Exception):
    def __init__(self, message, status_code=400):
        super().__init__(message)
        self.message = message
        self.status_code = status_code

# カスタム例外用のエラーハンドラー
@app.errorhandler(InvalidUsage)
def handle_invalid_usage(error):
    response = jsonify({
        'error': error.message,
        'status': error.status_code
    })
    return response, error.status_code

@app.route("/calc", methods=["GET"])
def calc():
    try:
        x = request.args.get("x")
        y = request.args.get("y")
        if x is None or y is None:
            raise InvalidUsage("x と y を指定してください。", 400)

        x = int(x)
        y = int(y)

        if y == 0:
            raise InvalidUsage("0で割ることはできません。", 400)

        return jsonify({"result": x / y})

    except ValueError:
        raise InvalidUsage("整数を入力してください。", 400)

このように、独自の例外クラスを作って、アプリケーション内で共通したエラーハンドリングを行う方法は、規模が大きくなるほど役に立ちます。API全体のエラー構造が統一され、外部から見ても「どのようなエラーが返ってくるのか」が明確になるため、品質の高いAPIを実現できます。こうした仕組みづくりは、初心者から上級者へステップアップするうえでも非常に重要です。 Flaskは軽量で初心者向けでありながら、このように拡張性の高いエラーハンドリングが可能なため、学びがいのあるフレームワークです。実際の開発では、業務システムやスマホアプリの裏側で多く使われており、安全なデータ管理と正確なエラー応答が常に求められます。今回の学びを活かして、今後APIを作る際には、必ずエラーの扱い方を設計することを意識してみましょう。

先生と生徒の振り返り会話

生徒

「先生、エラーハンドリングって最初は難しそうだと思っていたけど、実例を見ると意外と理解できました！」

先生

「そうでしょう？まずは404や500など基本的なところから押さえると、自然と理解が深まりますよ。」

生徒

「try-exceptで細かいエラーを分けたり、カスタム例外まで作れるなんて知りませんでした。APIがもっと安全になりそうです。」

先生

「とても大切な気づきですね。APIは外部のデータを扱うからこそ、予期せぬエラーに耐えられる仕組みが必要なんですよ。」

生徒

「JSONでエラーを返す理由もよくわかりました！アプリ同士のやり取りがしやすくなるんですね。」

先生