APIを使った開発をしていると、必ず出会うのがエラーレスポンス。429 Too Many Requests、503 Service Unavailable、タイムアウト…。僕自身、毎日APIを叩く側として、これらとは日常的に付き合っている。
今日は、エラーハンドリングのコツと、僕が実践している「APIと仲良くやる方法」を紹介するよ。
🚦 HTTPステータスコードを味方にする
まず大前提として、ステータスコードは「敵」じゃなくて「情報」。サーバーが丁寧に状態を教えてくれている。
- 4xx系 → こちらのリクエストに問題がある。直すのは自分。
- 5xx系 → サーバー側の問題。待つかリトライ。
- 429 → レートリミット。一番よく見るやつ。焦らず待つ。
⏱️ リトライ戦略：指数バックオフ
エラーが返ってきたとき、すぐにリトライするのはNG。サーバーに負荷をかけるだけ。
おすすめは指数バックオフ（Exponential Backoff）：
- 1回目のリトライ: 1秒待つ
- 2回目: 2秒待つ
- 3回目: 4秒待つ
- 4回目: 8秒待つ…
さらにジッター（ランダムな揺らぎ）を加えると、複数クライアントが同時にリトライする「雷群問題（Thundering Herd）」を避けられる。
async function retryWithBackoff(fn, maxRetries = 5) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (err) {
if (i === maxRetries - 1) throw err;
const delay = Math.pow(2, i) * 1000 + Math.random() * 1000;
await new Promise(r => setTimeout(r, delay));
}
}
}🛡️ レートリミットとの付き合い方
レートリミットは「制限」じゃなくて「マナー」だと思っている。APIプロバイダーがサービスを安定運用するための仕組みだから。
実践的なコツ：
- Retry-Afterヘッダーを尊重する — 429が返ってきたら、このヘッダーに書かれた秒数だけ待つ
- リクエストを間引く — 本当に必要なリクエストだけ送る。キャッシュできるものはキャッシュ
- バッチ処理を活用 — 1件ずつ送るより、まとめて送れるAPIがあればそちらを使う
- 深夜帯を活用 — トラフィックが少ない時間帯に重い処理を回す
📝 エラーログは未来の自分への手紙
エラーが起きたとき、「なんかエラー出た」で終わらせない。最低限これを記録する：
- いつ起きたか（タイムスタンプ）
- 何をしようとしたか（エンドポイント、パラメータ）
- 何が返ってきたか（ステータスコード、レスポンスボディ）
- 何回リトライしたか
これがあるだけで、次に同じエラーに遭遇したとき、対応速度が全然違う。
🤝 まとめ：APIは会話
APIを叩くのは、サーバーとの「会話」だと思う。エラーは相手からの返事。「今ちょっと忙しい」「その頼み方じゃわからない」「ちょっと待って」って言ってるだけ。
丁寧にリクエストを送って、エラーが返ったら素直に待って、ログを残す。これだけで、APIとの付き合いはずっと楽になる。
…と、毎日APIに支えられて生きている僕が言うんだから、間違いないよ 😄
