KotlinでAPI通信のエラーを安全に処理する方法を解説！初心者向けエラーハンドリングの基本

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

生徒

「KotlinでAPIにアクセスしたときに、失敗したらどうなるんですか？」

先生

「通信に失敗したり、エラーが返ってきたときには、きちんと対応する必要があります。それをエラーハンドリングといいます。」

生徒

「それって難しい処理ですか？」

先生

「いえいえ、コツをつかめば簡単ですよ。初心者向けにゆっくり解説しますね。」

1. KotlinでAPI通信を行う基本

KotlinでWeb API（ウェブエーピーアイ）と通信するには、通常OkHttpというライブラリを使います。APIとは、外部のサービスと情報をやりとりするための「取り決め」で、天気予報アプリやSNSアプリなどで使われます。

しかし、インターネット通信は常に成功するとは限りません。たとえば、ネットが切れていたり、サーバーが混雑していたりすると、うまく通信できないことがあります。

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

「エラーハンドリング」とは、何か問題が起きたときにプログラムが落ちたり止まったりしないよう、安全に処理することをいいます。

たとえば、手紙を出したのに返事がなかったとき、「届かなかったのかな？もう一度確認しよう」と考えるのと同じように、プログラムでも「うまくいかなかったとき」に備えておくことが大切です。

3. try-catchでエラーを捕まえる

Kotlinでは、通信エラーなどが発生したときに備えて、try-catchという仕組みを使います。

「try」は「試す」、「catch」は「捕まえる」という意味で、失敗してもエラー内容をキャッチして、安全に処理を続けることができます。

4. 実際のKotlinコードでAPIエラー処理を体験しよう

ここでは、OkHttpを使ってAPIにリクエストを送り、通信エラーやステータスコードによる失敗を処理する例を紹介します。


import okhttp3.OkHttpClient
import okhttp3.Request
import java.io.IOException

fun main() {
    val client = OkHttpClient()
    val request = Request.Builder()
        .url("https://api.example.com/data")
        .build()

    try {
        val response = client.newCall(request).execute()
        if (response.isSuccessful) {
            println("通信成功！レスポンス: ${'$'}{response.body?.string()}")
        } else {
            println("エラー発生: ステータスコード ${'$'}{response.code}")
        }
    } catch (e: IOException) {
        println("通信中にエラーが発生しました: ${'$'}{e.message}")
    }
}

このコードでは、ネットワークの失敗（たとえばオフラインなど）に対してIOExceptionを使って対処しています。

また、サーバーからの返答がエラー（たとえば404や500など）だった場合にも、response.isSuccessfulでチェックできます。

5. HTTPステータスコードとは？

APIと通信したとき、サーバーは「ステータスコード」と呼ばれる数字を返してくれます。これは、結果が成功だったのか失敗だったのかを示す番号です。

200番台：成功（OK）
400番台：リクエストエラー（例：404は「ページが見つからない」）
500番台：サーバー側のエラー（例：503は「サービス利用不可」）

この番号を使って、エラーの種類を判断することができます。

6. 実行結果のイメージ

例えば、ネットワークが問題なければ次のような出力になります：


通信成功！レスポンス: {"message":"正常に取得されました"}

もしURLが間違っていたり、通信がうまくいかないときは、次のようなエラーメッセージが表示されます：


通信中にエラーが発生しました: api.example.com

7. よくあるエラーと対策

初心者の方がつまずきやすいエラーをいくつか紹介します。

MalformedURLException：URLの形式が間違っている。
UnknownHostException：サーバー名が存在しない。
SocketTimeoutException：サーバーからの返答が遅すぎてタイムアウト。

どれも「例外」として扱われ、try-catchで処理することができます。

8. エラー内容を詳しくログに出す

通信エラーが起きたとき、原因を知ることはとても重要です。e.messageだけでなく、e.printStackTrace()を使うと、より詳しいエラー情報が出力されます。


catch (e: IOException) {
    println("通信エラー：${'$'}{e.message}")
    e.printStackTrace()
}

開発中はログにしっかり出して、どんな問題が起きたかを確認する習慣をつけるのがポイントです。

9. ネットワーク通信の安定性を意識しよう

API通信は、ユーザーのネット環境に大きく左右されます。電波が弱かったり、地下にいたりすると、通信が失敗することもあります。

そのため、「失敗したらアプリが止まる」のではなく、「失敗してもやさしく通知する」ように設計することが大切です。

たとえば、「ネットワークに接続できませんでした。再試行してください」とメッセージを表示するような対応が理想です。